Merge branch 'current' into next

Dockerfile

@@ -15,4 +15,4 @@ RUN pip3 install --no-cache-dir --no-binary :all: -r requirements.txt
 EXPOSE 8000
 WORKDIR /data/esphomedocs
 
-CMD ["make", "webserver"]
+CMD ["make", "live-html"]

Doxygen

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ESPHome"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2022.1.0
+PROJECT_NUMBER         = 2022.1.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

Makefile

@@ -1,10 +1,12 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2022.1.0
+ESPHOME_REF = 2022.1.2
 
-.PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
+.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
 
 html:
 	sphinx-build -M html . _build -j auto -n $(O)
+live-html:
+	sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0
 
 html-strict:
 	sphinx-build -M html . _build -W -j auto -n $(O)
@@ -48,9 +50,6 @@ copy-svg2png:
 
 netlify: netlify-dependencies netlify-api html copy-svg2png
 
-webserver: html
-	cd "_build/html" && python3 -m http.server
-
 lint: html-strict
 	python3 travis.py
 

_static/version

@@ -1 +1 @@
-2022.1.0
+2022.1.2

changelog/2022.1.0.rst

@@ -67,6 +67,18 @@ Example:
     JsonObject blah = root.createNestedObject("blah");
 
 
+Release 2022.1.1 - January 20
+-----------------------------
+
+- Add ``*.py.script`` files to distributions :esphomepr:`3074` by :ghuser:`jesserockz`
+
+Release 2022.1.2 - January 25
+-----------------------------
+
+- [modbus_controller] fix incorrect start address for number write :esphomepr:`3073` by :ghuser:`martgras`
+- Set the wrapped single light in light partition to internal :esphomepr:`3092` by :ghuser:`placidorevilla`
+
+
 Full list of changes
 --------------------
 

components/binary_sensor/template.rst

@@ -6,7 +6,8 @@ Template Binary Sensor
     :image: description.svg
 
 The ``template`` binary sensor platform allows you to define any :ref:`lambda template <config-lambda>`
-and construct a binary sensor out if it.
+and construct a binary sensor out if it. The lambda will run continuously; it isn't possible to specify
+an interval at which the lambda runs.
 
 For example, below configuration would turn the state of an ultrasonic sensor into
 a binary sensor.

components/button/index.rst

@@ -94,6 +94,13 @@ Configuration variables:
 
 - **id** (**Required**, :ref:`config-id`): The ID of the button to set.
 
+.. note::
+
+    Buttons are designed to trigger an action on a device from Home Assistant, and have an unidirectional flow from 
+    Home Assistant to ESPHome. If you press a button using this action, no button press event will be triggered in Home 
+    Assistant. If you want to trigger an automation in Home Assistant, you should use a
+    :ref:`Home Assistant event <api-homeassistant_event_action>` instead.
+
 .. _button-lambda_calls:
 
 lambda calls

components/climate/midea.rst

@@ -252,17 +252,17 @@ component, as well as control the light of the LED display.
             temperature: !lambda "return x;"
             beeper: false               # Optional. Beep on update.
 
-    # template momentary switches for sending display control command and swing step actions
-    switch:
+    # template buttons for sending display control command and swing step actions
+    button:
       - platform: template
         name: Display Toggle
         icon: mdi:theme-light-dark
-        turn_on_action:
+        on_press:
           midea_ac.display_toggle:
       - platform: template
         name: Swing Step
         icon: mdi:tailwind
-        turn_on_action:
+        on_press:
           midea_ac.swing_step:
 
 

components/display/max7219digit.rst

@@ -150,7 +150,7 @@ Screen inversion
           it.print(0,0, id(digit_font), "Hello!");
 
 The function ``it.invert_on_off(true);`` will invert the display. So background pixels are on and texts pixels are
-off. ``it.invert_on_off(false);`` sets the display back to normal. In case no argument is used: ``it.inverst_on_off();``
+off. ``it.invert_on_off(false);`` sets the display back to normal. In case no argument is used: ``it.invert_on_off();``
 the inversion will toggle from on to off or visa versa. This will happen every time the display is updated.
 So a blinking effect is created. The background pixels are only set at the next update, the pixels drawn in
 the various function like print, line, etc. are directly influenced by the invert command.

components/esp32_ble_tracker.rst

@@ -67,7 +67,7 @@ Configuration variables:
     Defaults to ``320ms``.
   - **window** (*Optional*, :ref:`config-time`): The time the ESP is actively listening for packets
     on a channel during each scan interval. If this is close to the ``interval`` value, the ESP will
-    spend more time listening to packets (but also consume more power).
+    spend more time listening to packets (but also consume more power). Defaults to ``30ms``
   - **duration** (*Optional*, :ref:`config-time`): The duration of each complete scan. This has no real
     impact on the device but can be used to debug the BLE stack. Defaults to ``5min``.
   - **active** (*Optional*, boolean): Whether to actively send scan requests to request more data

components/mcp230xx.rst

@@ -146,6 +146,9 @@ pins for your projects. Within ESPHome they emulate a real internal GPIO pin
 and can therefore be used with many of ESPHome's components such as the GPIO
 binary sensor or GPIO switch.
 
+GPIO pins in the datasheet are labelled A0 to A7 and B0 to B7, these are mapped
+consecutively in this component to numbers from 0 to 15.
+
 .. code-block:: yaml
 
     # Example configuration entry
@@ -156,10 +159,10 @@ binary sensor or GPIO switch.
     # Individual outputs
     switch:
       - platform: gpio
-        name: "MCP23017 Pin #0"
+        name: "MCP23017 Pin A0"
         pin:
           mcp23xxx: mcp23017_hub
-          # Use pin number 0
+          # Use pin A0
           number: 0
           mode:
             output: true
@@ -168,11 +171,11 @@ binary sensor or GPIO switch.
     # Individual inputs
     binary_sensor:
       - platform: gpio
-        name: "MCP23017 Pin #1"
+        name: "MCP23017 Pin B7"
         pin:
           mcp23xxx: mcp23017_hub
-          # Use pin number 1
-          number: 1
+          # Use pin B7
+          number: 15
           # One of INPUT or INPUT_PULLUP
           mode:
             input: true

components/mqtt.rst

@@ -419,7 +419,7 @@ Configuration variables:
 
     .. code-block:: cpp
 
-        id(mqtt_client).subscribe_json("the/topic", [=](JsonObject &root) {
+        id(mqtt_client).subscribe_json("the/topic", [=](const std::string &topic, JsonObject root) {
             // do something with JSON-decoded value root
         });
 
@@ -521,7 +521,7 @@ Configuration options:
 
     .. code-block:: cpp
 
-        id(mqtt_client).publish_json("the/topic", [=](JsonObject &root) {
+        id(mqtt_client).publish_json("the/topic", [=](JsonObject root) {
           root["something"] = id(my_sensor).state;
         });
 

components/sensor/bl0940.rst

@@ -41,9 +41,9 @@ to some pins on your board and the baud rate set to 4800 with 1 stop bit.
           name: 'BL0940 Power'
         energy:
           name: 'BL0940 Energy'
-        temperature:
+        internal_temperature:
           name: 'BL0940 Internal temperature'
-        target_temperature:
+        external_temperature:
           name: 'BL0940 External temperature'
         update_interval: 60s
 
@@ -58,9 +58,9 @@ Configuration variables:
   :ref:`Sensor <config-sensor>`.
 - **energy** (*Optional*): Use the voltage value of the sensor in kWh.
   All options from :ref:`Sensor <config-sensor>`.
-- **temperature** (*Optional*): The internal temperature value of the sensor in °C.
+- **internal_temperature** (*Optional*): The internal temperature value of the sensor in °C.
   All options from :ref:`Sensor <config-sensor>`.
-- **target_temperature** (*Optional*): The external value of the sensor in °C. Often not connected and gives garbage data.
+- **external_temperature** (*Optional*): The external value of the sensor in °C. Often not connected and gives garbage data.
   All options from :ref:`Sensor <config-sensor>`.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
   sensor. Defaults to ``60s``.

components/sensor/index.rst

@@ -196,7 +196,8 @@ the value the sensor shows.
 
 The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. ESPHome will
 then fit a linear equation to the values (using least squares). So you need to supply at least
-two values.
+two values. If more than two values are given a linear solution will be calculated and may not
+represent each value exactly.
 
 .. _sensor-calibrate_polynomial:
 

components/sensor/qmc5883l.rst

@@ -10,7 +10,7 @@ The ``qmc5883l`` allows you to use your QMC5883L triple-axis magnetometers
 (`datasheet <http://wiki.sunfounder.cc/images/7/72/QMC5883L-Datasheet-1.0.pdf>`__) with
 ESPHome. This sensor is very simular to the :ref:`HMC5883L <hmc5883l>` sensor and is oftern found
 as a knock off replacement. The QMC5883L sensor performs on par to the HMC5883L sensor,
-though the congiuration differs. The :ref:`I²C Bus <i2c>` is required to be set up in your
+though the configuration differs. The :ref:`I²C Bus <i2c>` is required to be set up in your
 configuration for this sensor to work.
 
 .. figure:: ../../images/qmc5883l.jpg

components/sensor/xiaomi_ble.rst

@@ -528,13 +528,18 @@ For this, you load the `application <https://zaluthar.github.io/TelinkFlasher.ht
 
 Other encrypted devices
 ***********************
-
+1.
 The easiest method (confirmed to work for LYWSD03MMC) is to use the `Telink flasher method <https://github.com/atc1441/ATC_MiThermometer>`__. The accompanying `video
 <https://www.youtube.com/watch?v=NXKzFG61lNs>`_ shows how to wirelessly flash a LYWSD03MMC, or how to obtain the bind key of the stock firmware (watch till around 13:10). The custom firmware allows you to change several settings of the device, including the smiley and the advertising interval. Keep in mind that when flashing the custom firmware, you need to enable the 'Advertising Type' to be 'Mi Like' and to give ESPHome a dummy bind key, as it still expects one even though the custom firmware does not encrypt the data.
 
+2.
 The other option is to use the original Mi Home app to add the sensor once. While adding the device, a new key is generated and uploaded into the Xiaomi cloud and to the device itself. Currently a chinese server needs to be selected as the rest of the world doesn't support most of these devices yet. Once generated, the key will not change again until the device is removed and re-added in the Xiaomi app.
 
-In order to obtain the bind key, a SSL packet sniffer needs to be setup on either an Android phone or the iPhone. A good choice for Android is the `Remote PCAP <https://play.google.com/store/apps/details?id=com.egorovandreyrm.pcapremote&hl=en>`__ in combination with `Wireshark <https://www.wireshark.org/>`__. A tutorial on how to setup the Remote PCAP packet sniffer can be found `here <https://egorovandreyrm.com/pcap-remote-tutorial/>`__ and `here <https://github.com/ahpohl/xiaomi_lywsd03mmc>`__. Instructions how to obtain the key using an iPhone are `here <https://github.com/custom-components/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key>`__. Once the traffic between the Mi Home app and the Xiaomi servers has been recorded, the bind key will show in clear text:
+2a.
+The easiest method to retrieve the bindkey from the cloud is to use the `Cloud Tokens Extractor <https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor>`__, written by one of Home Assistant users. If you prefer to not use the executable, read `here <https://www.home-assistant.io/integrations/xiaomi_miio/#xiaomi-cloud-tokens-extractor>`__.
+
+2b.
+Another option is to use a SSL packet sniffer. It can be setup on either an Android phone or the iPhone. A good choice for Android is the `Remote PCAP <https://play.google.com/store/apps/details?id=com.egorovandreyrm.pcapremote&hl=en>`__ in combination with `Wireshark <https://www.wireshark.org/>`__. A tutorial on how to setup the Remote PCAP packet sniffer can be found `here <https://egorovandreyrm.com/pcap-remote-tutorial/>`__ and `here <https://github.com/ahpohl/xiaomi_lywsd03mmc>`__. Instructions how to obtain the key using an iPhone are `here <https://github.com/custom-components/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key>`__. Once the traffic between the Mi Home app and the Xiaomi servers has been recorded, the bind key will show in clear text:
 
 .. code-block:: yaml
 
@@ -557,5 +562,6 @@ See Also
 - Custom firmware for the Xiaomi Thermometer LYWSD03MMC `<https://github.com/atc1441/ATC_MiThermometer>`__
 - TeLink flasher application `<https://atc1441.github.io/TelinkFlasher.html>`__
 - TeLink flasher application modified for CGDK2 `<https://zaluthar.github.io/TelinkFlasher.html>`__
+- Cloud Tokens Extractor: `<https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor>`__
 
 - :ghedit:`Edit`

conf.py

@@ -69,7 +69,7 @@ author = "Otto Winter"
 # The short X.Y version.
 version = "2022.1"
 # The full version, including alpha/beta/rc tags.
-release = "2022.1.0"
+release = "2022.1.2"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -81,7 +81,7 @@ language = "en"
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", 'env', 'venv', 'ENV', '.venv', '.env']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = 'cpp:any'

cookbook/tracer-an.rst

@@ -134,9 +134,6 @@ Below is the ESPHome configuration file that will get you up and running. This a
     ota:
       password: !secret ota_password
 
-    mqtt:
-      id: mqtt_client
-
     uart:
       id: mod_bus
       tx_pin: 19

cookbook/tuya_rgbw.rst

@@ -0,0 +1,88 @@
+Tuya RGBW LED controller
+========================
+
+The Tuya RGBW controller is inexpensive, available on ebay, and can be OTA flashed using `tuya-convert <https://github.com/ct-Open-Source/tuya-convert>`__, after which it can be OTA flashed via the ESPHome web interface (NOTE: a port must be explicitly set if using a Home Assistant add-on for this, and you need to connect directly to that port instead of using the proxied port via Home Assistant).
+
+.. figure:: images/tuya_rgbw.jpg
+    :align: center
+    :width: 80.0%
+
+The configuration below shows an example that can be compiled to a binary firmware file that works correctly for this device, and that cycles through three different brightnesses and an off state based on the number of button presses. The device can also be controlled via Home Assistant, of course, setting specific RGBW combinations and brightness levels.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    output:
+      - platform: esp8266_pwm
+        id: output_red
+        pin: GPIO14
+      - platform: esp8266_pwm
+        id: output_green
+        pin: GPIO5
+      - platform: esp8266_pwm
+        id: output_blue
+        pin: GPIO12
+      - platform: esp8266_pwm
+        id: output_white
+        pin: GPIO15
+
+    globals:
+      - id: action_state
+        type: int
+        restore_value: no
+        initial_value: '0'
+
+    binary_sensor:
+      - platform: gpio
+        pin:   GPIO13
+        name: "RGBW Controller Button"
+        filters:
+          - invert:
+          - delayed_on_off: 20ms
+        on_press:
+          then:
+            - lambda: id(action_state) = (id(action_state) + 1) % 4;
+            - if:
+                condition:
+                  lambda: 'return id(action_state) == 0;'
+                then:
+                  - light.turn_off:  rgbw_lightstrip1
+            - if:
+                condition:
+                  lambda: 'return id(action_state) == 1;'
+                then:
+                  - light.turn_on:
+                      id: rgbw_lightstrip1
+                      brightness: 60%
+            - if:
+                condition:
+                  lambda: 'return id(action_state) == 2;'
+                then:
+                  - light.turn_on:
+                      id: rgbw_lightstrip1
+                      brightness: 40%
+            - if:
+                condition:
+                  lambda: 'return id(action_state) == 3;'
+                then:
+                  - light.turn_on:
+                      id: rgbw_lightstrip1
+                      brightness: 15%
+    light:
+      - platform: rgbw
+        name: "rgbw_strip_01"
+        id: rgbw_lightstrip1
+        red: output_red
+        green: output_green
+        blue: output_blue
+        white: output_white
+
+        # Ensure the light turns on by default if the physical switch is actuated.
+        restore_mode: ALWAYS_OFF
+
+See Also
+--------
+
+- :doc:`/components/light/rgbw`
+- :doc:`/components/output/esp8266_pwm`
+- :ghedit:`Edit`

devices/esp32.rst

@@ -8,7 +8,7 @@ Generic ESP32
 
 All devices based on the original ESP32 are supported by ESPHome. Simply select ``ESP32`` when
 the ESPHome wizard asks you for your platform and choose a board type
-from `this link <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif32>`__ when the wizard
+from `this link <https://registry.platformio.org/platforms/platformio/espressif32/boards>`__ when the wizard
 asks you for the board type.
 
 .. code-block:: yaml

guides/contributing.rst

@@ -28,6 +28,111 @@ setup, please feel free to submit a pull request.
 The ESPHome documentation is built using `sphinx <http://www.sphinx-doc.org/>`__ and uses
 `reStructuredText <http://docutils.sourceforge.net/rst.html>`__ for all source files.
 
+If you're not familiar with writing rST, see :ref:`rst-syntax` for a quick refresher.
+
+Through Github
+**************
+
+This guide essentially goes over the same material found in `GitHub's Editing files in another user's repository <https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository>`__. You may also find that page helpful to read.
+
+At the bottom of each page in the docs, there is a "Edit this page on GitHub" link. Click this link and you'll see something like this:
+
+.. figure:: images/docs_ghedit_1.png
+    :align: center
+    :width: 80.0%
+    :alt: a screenshot of an rST file opened in GitHub, with the edit button circled
+
+Click the edit button to start making changes. If you're not sure about some element of syntax, see the quick-start :ref:`rst-syntax` guide.
+
+Once you've made your changes, give them a useful name and press "Propose changes". At this point, you've made the changes on your own personal copy of the docs in GitHub, but you still need to submit them to us.
+
+.. figure:: images/docs_ghedit_2.png
+    :align: center
+    :width: 80.0%
+    :alt: the commit creation screen in GitHub, with the commit title and "Propose changes" button circled
+
+To do that, you need to create a "Pull request":
+
+.. figure:: images/docs_ghedit_3.png
+    :align: center
+    :width: 80.0%
+    :alt: the pull request prompt screen in GitHub with the "Create pull request" button circled
+
+Fill out the new pull request form, replacing the ``[ ]`` with ``[x]`` to indicate that you have followed the instructions.
+
+.. figure:: images/docs_ghedit_4.png
+    :align: center
+    :width: 80.0%
+    :alt: the pull request creation screen in GitHub with the "Create pull request" button circled
+
+After waiting a while, you might see a green or a red mark next to your commit in your pull request:
+
+.. figure:: images/docs_ghedit_ci_failed.png
+    :align: center
+    :width: 80.0%
+    :alt: the pull request with a commit with a red x next to it
+
+This means that there is some error stopping your pull request from being fully processed. Click on the X, click on "Details" next to the lint step, and look and see what's causing your change to fail.
+
+.. figure:: images/docs_ghedit_ci_details.png
+    :align: center
+    :width: 80.0%
+    :alt: failed lint substep of build, with "details" link circled
+
+.. figure:: images/docs_ghedit_ci_logs.png
+    :align: center
+    :width: 80.0%
+    :alt: log messages showing reason for failed build
+
+For example, in this case, you'd want to go to line 136 of ``pzemac.rst`` and adjust the number of ``===`` so that it completely underlines the section heading.
+
+Once you make that change, the pull request will be built again, and hopefully this time where will be no other errors.
+
+Build
+*****
+
+.. note::
+
+    The easiest way is to use the `esphome-docs Docker image <https://hub.docker.com/r/esphome/esphome-docs/>`__:
+
+    .. code-block:: bash
+
+        docker run --rm -v "${PWD}/":/data/esphomedocs -p 8000:8000 -it esphome/esphome-docs
+
+    With ``PWD`` referring to the root of the ``esphome-docs`` git repository. Then go to ``<CONTAINER_IP>:8000`` in your browser.
+
+    This way, you don't have to install the dependencies to build the documentation.
+
+To check your documentation changes locally, you first need install Sphinx (with **Python 3**).
+
+.. code-block:: bash
+
+    # in ESPHome-Docs repo:
+    pip install -r requirements.txt
+
+Then, use the provided Makefile to build the changes and start a live-updating web server:
+
+.. code-block:: bash
+
+    # Start web server on port 8000
+    make live-html
+
+Notes
+*****
+
+Some notes about the docs:
+
+- Use the English language (duh...)
+- An image tells a thousand words, please use them wherever possible. But also don't forget to shrink them, for example
+  I often use https://tinypng.com/
+- Try to use examples as often as possible (also while it's great to use highly accurate,
+  and domain-specific lingo, it should not interfere with new users understanding the content)
+- Fixes/improvements for the docs themselves should go to the ``current`` branch of the
+  esphomedocs repository. New features should be added against the ``next`` branch.
+- Always create new branches in your fork for each pull request.
+
+.. _rst-syntax:
+
 Syntax
 ******
 
@@ -123,13 +228,13 @@ documents establish the following character order for better consistency.
 
   .. code-block:: rst
 
-      .. figure:: images/dashboard.png
+      .. figure:: images/dashboard_states.png
           :align: center
           :width: 40.0%
 
           Optional figure caption.
 
-  .. figure:: images/dashboard.png
+  .. figure:: images/dashboard_states.png
       :align: center
       :width: 40.0%
 
@@ -214,52 +319,6 @@ documents establish the following character order for better consistency.
 reStructured text can do a lot more than this, so if you're looking for a more complete guide
 please have a look at the `Sphinx reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__.
 
-Build
-*****
-
-.. note::
-
-    The easiest way is to use the `esphome-docs Docker image <https://hub.docker.com/r/esphome/esphome-docs/>`__:
-
-    .. code-block:: bash
-
-        docker run --rm -v "${PWD}/":/data/esphomedocs -p 8000:8000 -it esphome/esphome-docs
-
-    With ``PWD`` referring to the root of the ``esphome-docs`` git repository. Then go to ``<CONTAINER_IP>:8000`` in your browser.
-
-    This way, you don't have to install the dependencies to build the documentation.
-
-To check your documentation changes locally, you first need install Sphinx (with **Python 3**).
-
-.. code-block:: bash
-
-    # in ESPHome-Docs repo:
-    pip install -r requirements.txt
-
-Then, use the provided Makefile to build the changes and start a simple web server:
-
-.. code-block:: bash
-
-    # Start web server on port 8000
-    make webserver
-
-    # Updates then happen via:
-    make html
-
-Notes
-*****
-
-Some notes about the docs:
-
-- Use the English language (duh...)
-- An image tells a thousand words, please use them wherever possible. But also don't forget to shrink them, for example
-  I often use https://tinypng.com/
-- Try to use examples as often as possible (also while it's great to use highly accurate,
-  and domain-specific lingo, it should not interfere with new users understanding the content)
-- Fixes/improvements for the docs themselves should go to the ``current`` branch of the
-  esphomedocs repository. New features should be added against the ``next`` branch.
-- Always create new branches in your fork for each pull request.
-
 .. _setup_dev_env:
 
 Setting Up Development Environment

guides/getting_started_command_line.rst

@@ -1,5 +1,5 @@
-Getting Started with ESPHome
-============================
+Getting Started with the ESPHome Command Line
+=============================================
 
 .. seo::
     :description: Getting Started guide for installing ESPHome using the command line and creating a basic configuration.
@@ -12,27 +12,27 @@ basic “node” in a few simple steps.
 Installation
 ------------
 
-Installing ESPHome is very easy. All you need to do is have `Python
-<https://www.python.org/>`__ installed and install the console script through
-``pip3``.
+See :doc:`installing_esphome`.
 
-.. note::
-
-    Python 3.7 or above is required to install ESPHome 1.18.0 or above.
-
-
-.. code-block:: bash
-
-    pip3 install esphome
-
-Alternatively, there’s also a Docker image available for easy
-installation (the Docker hub image is available for AMD64, ARM and ARM64(AARCH64) right now; if you have
-another architecture, please install ESPHome through ``pip`` or use :doc:`the Home Assistant add-on <getting_started_hassio>`:
+If you're familiar with Docker, you can use that instead! Our image supports
+AMD64, ARM and ARM64 (AARCH64), and can be downloaded with:
 
 .. code-block:: bash
 
     docker pull esphome/esphome
 
+Connecting the ESP Device
+-------------------------
+
+Follow the instructions in :doc:`physical_device_connection` to connect to your
+ESP device.
+
+.. note::
+
+    The most difficult part of setting up a new ESPHome device is the initial
+    installation. Installation requires that your ESP device is connected with
+    a cable to a computer. Later updates can be installed wirelessly.
+
 Creating a Project
 ------------------
 
@@ -189,7 +189,7 @@ To start the ESPHome dashboard, simply start ESPHome with the following command
 
 After that, you will be able to access the dashboard through ``localhost:6052``.
 
-.. figure:: images/dashboard.png
+.. figure:: images/dashboard_states.png
 
 See Also
 --------

guides/getting_started_hassio.rst

@@ -5,12 +5,10 @@ Getting Started with ESPHome and Home Assistant
     :description: Getting Started guide for installing ESPHome Dashboard as a Home Assistant add-on and creating a basic configuration.
     :image: home-assistant.svg
 
-ESPHome is the perfect solution for creating custom firmware for
-your ESP8266/ESP32 boards. In this guide we’ll go through how to setup a
-basic "node" using the ESPHome Dashboard, installed as a Home Assistant add-on.
+In this guide we’ll go through how to install ESPHome on a device using the ESPHome Dashboard, installed as a Home Assistant add-on.
 
 But first, here's a very quick introduction to how ESPHome works:
-ESPHome is a *tool* which aims to make managing your ESP boards as simple as possible. It reads in a YAML configuration file (just like Home Assistant) and creates custom firmware which it installs on your ESP device. Devices or sensors added in ESPHome's configuration will automatically show up in Home Assistant's UI.
+ESPHome is a *tool* which aims to make managing your ESP boards as simple as possible. It reads in a YAML configuration file and creates custom firmware which it installs on your ESP device. Devices or sensors added in ESPHome's configuration will automatically show up in Home Assistant's UI.
 
 Installing ESPHome Dashboard
 ----------------------------
@@ -30,29 +28,17 @@ After that, wait a bit until it is installed (this can take a while). Click "Sta
 You should now be greeted by a nice introduction wizard which will step you through
 creating your first configuration.
 
-.. figure:: images/hassio_start.png
+.. figure:: images/dashboard_empty.png
     :align: center
     :width: 95.0%
 
 The wizard will guide you through creating your first configuration and, depending on your browser, install it on your ESP device. You will need to name your configuration and enter your wireless network settings so that the ESP device can come online and can communicate with Home Assistant.
 
-.. raw:: html
-
-    <a name='webserial'></a>
-
 .. note::
 
     The most difficult part of setting up a new ESPHome device is the initial installation. Installation requires that your ESP device is connected with a cable to a computer. Later updates can be installed wirelessly.
 
-    If you use `Microsoft Edge <https://www.microsoft.com/edge>`_ or `Google Chrome <https://www.google.com/chrome>`_, you will be able to install the initial configuration by connecting your ESP device to the computer that you're using to view the ESPHome Dashboard.
-    *You need to access the ESPHome Dashboard over HTTPS for this to work. This is a requirement of browsers to access your ESP device to ensure that we write the correct data.*
-
-    If you use another browser, you will have to connect the ESP devices to the machine running the ESPHome Dashboard and Home Assistant.
-
-    If the serial port is not showing up, you might not have the required drivers installed. These drivers work for most ESP devices:
-
-      * CP2102 (square chip): `driver <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`__
-      * CH341: `driver <https://github.com/nodemcu/nodemcu-devkit/tree/master/Drivers>`__
+    For guidance on making this first connection, see :doc:`physical_device_connection`
 
 
 Dashboard Interface
@@ -61,24 +47,30 @@ Dashboard Interface
 Assuming you created your first configuration file with the wizard, let's take a quick
 tour of the ESPHome Dashboard interface.
 
-.. figure:: images/dashboard.png
+.. figure:: images/dashboard_states.png
     :align: center
     :width: 95.0%
 
 On the front page you will see all configurations for nodes you created. For each file,
-there are three basic actions you can perform:
+there are a few basic actions you can perform:
 
-- **INSTALL**: This compiles the firmware for your node and installs it. Installation happens wirelessy if you have enabled the :doc:`/components/ota` in your configuration. Alternatively you can install it from your browser or via a device connected to the machine running the ESPHome Dashboard.
+- **UPDATE**: This button will show up if the device has not been installed with the same ESPHome version currently running.
 
-- **SHOW LOGS**: With this command you can view all the logs the node is outputting. If a USB device is
-  connected, it will attempt to use the serial connection. Otherwise it will use the built-in OTA logs.
+- **EDIT**: This will open the configuration editor.
 
-- **COMPILE**: This command compiles the firmware and gives you the option of downloading the generated
-  binary so that you can install it yourself from your computer using :ref:`ESPHome-flasher <esphome-flasher>`.
+- **LOGS**: With this command you can view all the logs the node is outputting. If a USB device is
+  connected, you can choose to use the serial connection. Otherwise it will use the built-in OTA logs.
+
+- **Overflow menu**: This is a dropdown menu which allows you to perform more actions.
+
+  - **Validate**: This will validate the configuration file.
+  - **Install**: Opens the Install dialog.
+  - **Clean Build Files**: This will delete all of the generated build files and is a safe operation to perform. Sometimes old files are not removed and can cause compile issues later on.
+  - **Delete**: This will delete the configuration file.
 
 The configuration files for ESPHome can be found and edited under ``<HOME_ASSISTANT_CONFIG>/esphome/``.
-For example the configuration for the node in the picture above can be found
-in ``/config/esphome/livingroom.yaml``.
+For example the configuration for the ``garage-door`` node in the picture above can be found
+in ``/config/esphome/garage-door.yaml``.
 
 Now go ahead and use one of the :ref:`devices guides <devices>` to extend your configuration.
 

guides/installing_esphome.rst

@@ -0,0 +1,111 @@
+Installing ESPHome Manually
+===========================
+
+Windows
+-------
+
+Download Python from `the official site <https://www.python.org/downloads/>`_.
+
+.. figure:: images/python-win-installer.png
+    :align: center
+    :width: 75.0%
+    :alt: Python installer window with arrows pointing to "Add Python to PATH" and "Install Now"
+
+Make sure you check "Add Python to PATH", and go all the way through the
+installer.
+
+Log out and back in, or restart your computer. Whichever is easiest.
+
+Open the start menu and type ``cmd``. Press the enter key.
+
+In the terminal that comes up, check that Python is installed:
+
+.. code-block:: console
+
+    > python --version
+    Python 3.10.1
+
+.. note::
+
+    Don't copy the ``>``. That's used to show that this is a command that goes
+    in the console, and to let you see what the expected results are (shown on
+    the next line without a ``>``)
+
+Looks good? You can go ahead and install ESPHome:
+
+.. code-block:: console
+
+    > pip3 install wheel
+    > pip3 install esphome
+
+And you should be good to go! You can test that things are properly installed
+with the following:
+
+.. code-block:: console
+
+    > esphome version
+    Version: 2021.12.3
+
+Mac
+---
+
+There are no tested installation instructions for Mac. ESPHome does support
+Mac & will run with no problem.
+
+Contributions are welcome!
+
+The process will likely be similar to Windows. You can install Python from the
+official site, and then install ESPHome with ``pip3 install esphome``.  You can
+then test that things are properly installed with the following:
+
+.. code-block:: console
+
+    $ esphome version
+    Version: 2021.12.3
+
+Linux
+-----
+
+Your distribution probably already has Python installed. Confirm that it is at
+least version 3.7:
+
+.. code-block:: console
+
+    $ python3 --version
+    Python 3.7.1
+
+Looks good? You can go ahead and install ESPHome:
+
+.. code-block:: bash
+
+    pip3 install --user esphome
+
+.. caution::
+
+    Don't use ``sudo`` with pip. If you do, you'll run into trouble updating
+    your OS down the road.
+
+    For details, see `DontBreakDebian
+    <https://wiki.debian.org/DontBreakDebian#A.27make_install.27_can_conflict_with_packages>`_.
+    ``pip install`` is equivalent to ``make install`` in this context. The
+    advice in the article applies to all Linux distributions, not just Debian.
+
+At this point, you should be able confirm that ESPHome has been successfully installed:
+
+.. code-block:: console
+
+    $ esphome version
+    Version: 2021.12.3
+
+If you get an error like "Command not found", you need to add the binary to
+your ``PATH`` using ``export PATH=$PATH:$HOME/.local/bin``.
+
+To set this permanently, you can run ``echo 'export
+PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc``, then log out and back in.
+
+See Also
+--------
+
+- :doc:`ESPHome index </index>`
+- :doc:`getting_started_command_line`
+- :ghedit:`Edit`

guides/physical_device_connection.rst

@@ -0,0 +1,329 @@
+Physically Connecting to your Device
+====================================
+
+The most difficult part of setting up a new ESPHome device is the initial
+installation, which requires connecting your ESP device to a computer using a
+cable.
+
+**You only need to do this once per device.** Once you've flashed ESPHome on a
+device, you can use :doc:`the OTA updater </components/ota>` to upload new
+versions or configuration changes wirelessly.
+
+ESPHome runs on a wide variety of devices, so it's hard to list any specific
+set of tools that you need or to give instructions on how to connect. This
+guide tries to cover some of the more common flashing situations. If your
+device doesn't fit any of these situations, try and find a guide for your
+specific device in the :ref:`devices guides <devices>` or elsewhere on the
+internet.
+
+Connecting to the ESP
+---------------------
+
+There's a wide variety of situations you might find yourself in, each of which
+requires you do something different to connect your computer to the ESP in
+order to flash it.
+
+You only need to physically connect to it once. Once you've flashed your device
+and connected it to your WiFi, you can use the `OTA (over-the-air) update
+component </components/ota.html>`_ to install software remotely.
+
+Programming a ESP-based device is done by connecting the serial port on the
+ESP8266/ESP32 to your computer through a USB to serial adapter. Some devices
+have adapter built into the circuit board, in which case things are a bit easier.
+
+.. note::
+
+    If the serial port is not showing up, you might not have the required
+    drivers installed. The model number you need is engraved on the chip
+    connected to the USB port, or in the store listing. These drivers work for
+    most ESP devices:
+
+      * CP2102 (square chip): `driver
+        <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`__
+      * CH341: `driver
+        <https://github.com/nodemcu/nodemcu-devkit/tree/master/Drivers>`__
+
+With the exception of the situation where you have a USB port, you need to make
+five electrical connections to program an ESP-based board:
+
+- +3.3V, or occasionally +5.0V
+- GND, or ground
+- TX
+- RX
+- IO0, used to place the board into programming mode. This is often a button
+  that you need to hold down while connecting the power (+3.3V).
+
+RX and TX are frequently swapped. If programming your board doesn't work the
+first time, try flipping the wires connected to those pins before trying again.
+
+.. warning::
+
+    .. image:: /images/high-voltage-warning.svg
+      :alt: High voltage warning symbol
+      :height: 50
+
+    **Do not connect your device to mains electricity while following this
+    guide.** If your device is open and plugged directly into the wall, you'll
+    be a single touch away from being electrocuted.
+
+    Note that this does not apply if your device uses a separate "wall wart" or
+    a power brick. Using an external power supply while flashing is an advanced
+    topic not covered here, but does not pose any safety risk.
+
+    **You are solely responsible for your own safety.** If you feel something
+    is wrong or are uncomfortable with continuing, stop immediately.
+
+USB Port on Device
+******************
+
+.. figure:: /images/nodemcu_esp8266.jpg
+    :align: center
+    :width: 75.0%
+
+    A device with a USB port and a serial adapter built-in
+
+Development boards often come with a USB port built in. This USB port is
+connected to a serial adapter, so you don't need a separate serial adapter. You
+can use just a :ref:`USB cable <usb-cable>` to connect it to your computer to
+program it.
+
+This isn't likely to be very useful without connecting additional sensors to it
+by either soldering or using a breadboard, but you do not need anything else to
+*just* flash ESPHome on it.
+
+Pre-soldered Programming Header
+*******************************
+
+.. figure:: images/programming-header-populated.jpg
+    :align: center
+    :width: 75.0%
+
+    A device that comes with programming headers pre-installed
+
+In this situation, you'll need just :ref:`jumper wires <jumper-wires>` and a
+:ref:`USB to serial adapter <usb-serial-adapter>`. You don't need to solder
+anything, that's already been done by the factory.
+
+Unpopulated Programming Header
+******************************
+
+.. figure:: images/programming-header-unpopulated.jpg
+    :align: center
+    :width: 75.0%
+
+    A device that has a spot for programming headers on the circuit board
+
+You can probably get away with :ref:`jumper wires <jumper-wires>` and a
+:ref:`USB to serial adapter <usb-serial-adapter>`. You can place the male end
+of the wires directly into the circuit board and hold them into place with your
+hand until you're done flashing the board.
+
+These headers sometimes have writing on the circuit board indicating what each
+pin is. If your header does not, either look it up on the internet, or use a
+multimeter in continuity mode to figure it out (advanced topic).
+
+Solder-filled Programming Header
+********************************
+
+.. figure:: images/programming-header-filled.jpg
+    :align: center
+    :width: 75.0%
+
+    A set of programming headers that are filled with solder
+
+You'll need a USB to serial adapter, :ref:`jumper wires <jumper-wires>`, a
+:ref:`soldering iron <soldering-iron>`, and probably :ref:`solder <solder>` and
+some :ref:`breakaway headers <pcb-headers>` if your board looks like this.
+
+You can try placing the jumper wires in the right place, but you'll have
+trouble holding them without having them slide around. You'll want to solder a
+header onto the programming port in this situation.
+
+These headers sometimes have writing on the circuit board indicating what each
+pin is. If your header does not, either look it up on the internet, or use a
+multimeter in continuity mode to figure it out (advanced topic).
+
+Module Only
+***********
+
+.. figure:: images/module-only-programming.jpg
+    :align: center
+    :width: 75.0%
+    :alt: From https://tasmota.github.io/docs/devices/SM-SO301/
+
+    An ESP8266 module with programming wires soldered on
+
+If the device has a module but no programming headers, things get a bit tricky.
+You'll need a :ref:`USB to serial adapter <usb-serial-adapter>`, :ref:`jumper
+wires <jumper-wires>`, :ref:`wire strippers <wire-strippers>`, :ref:`wire snips
+<wire-snips>`, a :ref:`soldering iron <soldering-iron>`, :ref:`solder
+<solder>`, and a bit of :ref:`flux <soldering-flux>` would help.
+
+Cut the jumper wires, strip a bit off the end, and then solder them onto the
+module. You can find the correct places to solder the wires by looking up the
+module model number on the internet. You can find `one list of commonly used
+modules here <https://tasmota.github.io/docs/Pinouts/>`_.
+
+Bare Chip
+*********
+
+.. figure:: images/programming-bare-chip.jpg
+    :align: center
+    :width: 75.0%
+    :alt: From https://tasmota.github.io/docs/devices/Teckin-SP23/
+
+    A bare ESP8266 IC with no programming header
+
+This is an advanced topic and won't be covered in detail, but you have three options:
+
+- You can hope that your device is supported by an OTA conversation tool. Most
+  these tools have been broken by vendors, and the ESPHome community can't help
+  you with using these tools.
+- If the programming wires connect to a larger component like a resistor, you
+  can solder or clip your :ref:`jumper wires <jumper-wires>` to that larger
+  component.
+- You can use your amazing microsoldering skills to connect directly to the IC.
+
+Materials
+---------
+
+Because we're working with hardware, we might need some additional tools,
+depending on the situation. Already have all this stuff? You're good to go!
+
+But if you don't, don't go out and buy everything just yet. Read through the
+guide first and make a list of everything you need. Different situations will
+require different parts and tools.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 1 3 1 3
+
+    * - Name
+      - Purpose
+      - Approx. cost
+      - Picture
+
+        .. _usb-cable:
+    * - :ref:`USB to micro-USB/mini-USB/USB-C <usb-cable>`
+      - If your target device has a USB port on it, you need the appropriate
+        cable to connect to it.
+      - $3 to $10
+      - .. image:: /guides/images/usb-cable.jpg
+            :alt: From https://www.stockvault.net/photo/271754/usb-cable
+
+        .. _usb-serial-adapter:
+    * - :ref:`USB to serial adapter <usb-serial-adapter>`
+      - Serial communication is a simple way of talking to other devices, like
+        the ESP32/ESP8266 you're flashing. But your computer probably doesn't
+        have this capability built-in. "Serial", "UART", "TTL", and "COM" are
+        all more-or-less synonyms.
+
+        There are many different types of these, so don't worry if yours doesn't
+        look exactly like the picture. However, you do need one with a voltage
+        regulator.
+
+        The `Tasmota website provides a good set of suggestions on what to buy
+        <https://tasmota.github.io/docs/Getting-Started/#needed-hardware>`_.
+      - $3 to $10
+      - .. image:: /guides/images/usb-serial-adapter.jpg
+            :alt: From https://tasmota.github.io/docs/Getting-Started/
+
+        .. _jumper-wires:
+    * - :ref:`Jumper wires <jumper-wires>`
+      - Used to connect two things together electrically. The male end has metal
+        protuding and is plugged into the the female end of a wire or board.
+        They come in varying lengths too, but for our purposes, any length will
+        do.
+      - $3 to $8 for a pack
+      - .. image:: /guides/images/jumper-wires.jpg
+            :alt: From https://www.flickr.com/photos/snazzyguy/8096512976
+
+        .. _pcb-headers:
+    * - :ref:`Breakable headers <pcb-headers>`
+      - Soldered to a PCB to provide a way to connect jumper wires. The distance
+        between the metal pins is known as the pitch, and is usually 2.54mm for
+        what we're doing.
+
+        This sort of header can be cut to the correct length along the groves.
+      - $3 to $8 for a pack
+      - .. image:: /guides/images/breakable-header.jpg
+            :alt: From https://www.flickr.com/photos/snazzyguy/27120004896/
+
+        .. _wire-snips:
+    * - :ref:`Wire snips, wire cutters, flush cutters <wire-snips>`
+      - Used to cut wire. These can often be subsituted by a knife or scissors,
+        but be careful not to hurt yourself.
+      - $5 to $15
+      - .. image:: /guides/images/wire-cutters.jpg
+            :alt: From https://www.flickr.com/photos/snazzyguy/3932324106
+
+        .. _wire-strippers:
+    * - :ref:`Wire strippers <wire-strippers>`
+      - Used to remove the insulation from wires, leaving the conductive metal
+        interior exposed. These can often be subsituted by a knife, scissors, or
+        fingernails, but be careful not to hurt yourself.
+
+        There are many different styles, not just that in the picture. You'll
+        want something that works with fairly thin wire, about 20 AWG to 26 AWG.
+      - $5 to $15
+      - .. image:: /guides/images/strippers.jpg
+            :alt: From https://www.flickr.com/photos/snazzyguy/3931542659
+
+        .. _soldering-iron:
+    * - :ref:`Soldering iron <soldering-iron>`
+      - Used to melt metal, called solder, to connect things together in an
+        electrically conductive way.
+
+        You'll want something with temperature control. Other than that, there
+        are many varying opinions and options here.
+
+        `The /r/AskElectronics wiki has some good suggestions
+        <https://www.reddit.com/r/AskElectronics/wiki/soldering>`_. The
+        following would serve you well, although be careful to buy from a
+        reliable source:
+
+        - Hakko FX-888D
+        - KSGER T12
+        - TS100/TS80
+      - $60 to $120
+      - .. image:: /guides/images/soldering-iron.jpg
+            :alt: From https://commons.wikimedia.org/wiki/File:Soldering_Station_Weller_2.jpeg
+
+        .. _solder:
+    * - :ref:`Electronics solder <solder>`
+      - Molten metal used to join things in an electrically conductive way.
+        There are two types, leaded and lead-free. Leaded melts at a lower
+        temperature and is a little easier to work with, but is hazardous to the
+        environment (but not to humans in this form).
+
+        Electronics solder also usually has a "rosin core", which helps clean
+        the surfaces to allow the solder to stick.
+
+        You absolutely do not want plumbing solder, also known as "acid core" or
+        "silver solder". It needs much higher temperatures than we can safely
+        use here.
+      - $8 to $12
+      - .. image:: /guides/images/solder.jpg
+            :alt: From https://commons.wikimedia.org/wiki/File:Rosin_core_solder.JPG
+
+        .. _soldering-flux:
+    * - :ref:`Electronics flux <soldering-flux>`
+      - Used to clean the metal surfaces before soldering them together.
+        Sometimes the rosin core of the solder doesn't provide enough, so you'd
+        want add some extra.
+
+        This stuff is helpful, but probably not needed for this guide since we
+        won't be doing any advanced soldering.
+
+        If you do buy it, you absolutely do not want plumber's flux. It will
+        destroy your circuit boards.
+      - $8 to $12
+      - .. image:: /guides/images/flux.jpg
+
+See Also
+--------
+
+- :doc:`ESPHome index </index>`
+- :doc:`getting_started_command_line`
+- :doc:`getting_started_hassio`
+- :ghedit:`Edit`

guides/supporters.rst

@@ -32,7 +32,6 @@ Contributors
 - `adamgreg (@adamgreg) <https://github.com/adamgreg>`__
 - `Chris Byrne (@adapt0) <https://github.com/adapt0>`__
 - `Attila Darazs (@adarazs) <https://github.com/adarazs>`__
-- `adezerega (@adezerega) <https://github.com/adezerega>`__
 - `Andrea Donno (@adonno) <https://github.com/adonno>`__
 - `Adrien Brault (@adrienbrault) <https://github.com/adrienbrault>`__
 - `Johan Bloemberg (@aequitas) <https://github.com/aequitas>`__
@@ -51,10 +50,8 @@ Contributors
 - `Alex Barcelo (@alexbarcelo) <https://github.com/alexbarcelo>`__
 - `Alexandre Danault (@AlexDanault) <https://github.com/AlexDanault>`__
 - `Alex Iribarren (@alexiri) <https://github.com/alexiri>`__
-- `alexmaurer-madis (@alexmaurer-madis) <https://github.com/alexmaurer-madis>`__
 - `Alex Mekkering (@AlexMekkering) <https://github.com/AlexMekkering>`__
 - `Alex (@alexyao2015) <https://github.com/alexyao2015>`__
-- `aliktb (@aliktb) <https://github.com/aliktb>`__
 - `Amish Vishwakarma (@amishv) <https://github.com/amishv>`__
 - `Jason Nader (@ammgws) <https://github.com/ammgws>`__
 - `anatoly-savchenkov (@anatoly-savchenkov) <https://github.com/anatoly-savchenkov>`__
@@ -63,14 +60,11 @@ Contributors
 - `Andreas Hergert (@andreashergert1984) <https://github.com/andreashergert1984>`__
 - `Andrzej (@andriej) <https://github.com/andriej>`__
 - `Andreas (@anduchs) <https://github.com/anduchs>`__
-- `anekinloewe (@anekinloewe) <https://github.com/anekinloewe>`__
-- `Vegetto (@angelnu) <https://github.com/angelnu>`__
+- `Angel Nunez Mencias (@angelnu) <https://github.com/angelnu>`__
 - `Sergey Anisimov (@anisimovsergey) <https://github.com/anisimovsergey>`__
-- `ankycooper (@ankycooper) <https://github.com/ankycooper>`__
 - `Nikolay Vasilchuk (@Anonym-tsk) <https://github.com/Anonym-tsk>`__
 - `Adriaan Peeters (@apeeters) <https://github.com/apeeters>`__
 - `Darius Ratkevičius (@aphex008) <https://github.com/aphex008>`__
-- `aquaticus (@aquaticus) <https://github.com/aquaticus>`__
 - `Andy Allsopp (@arallsopp) <https://github.com/arallsopp>`__
 - `arantius (@arantius) <https://github.com/arantius>`__
 - `arunderwood (@arunderwood) <https://github.com/arunderwood>`__
@@ -97,6 +91,7 @@ Contributors
 - `Arturo Casal (@berfenger) <https://github.com/berfenger>`__
 - `Ivan Bessarabov (@bessarabov) <https://github.com/bessarabov>`__
 - `besteru (@besteru) <https://github.com/besteru>`__
+- `Brandon (@bgulla) <https://github.com/bgulla>`__
 - `Bierchermuesli (@Bierchermuesli) <https://github.com/Bierchermuesli>`__
 - `JDavid (@blackhack) <https://github.com/blackhack>`__
 - `Branimir Lambov (@blambov) <https://github.com/blambov>`__
@@ -104,7 +99,6 @@ Contributors
 - `Bob (@Bmooij) <https://github.com/Bmooij>`__
 - `Mauricio Bonani (@bonanitech) <https://github.com/bonanitech>`__
 - `Casey Olson (@bookcasey) <https://github.com/bookcasey>`__
-- `boradwell (@boradwell) <https://github.com/boradwell>`__
 - `BoukeHaarsma23 (@BoukeHaarsma23) <https://github.com/BoukeHaarsma23>`__
 - `Patrik Hermansson (@bphermansson) <https://github.com/bphermansson>`__
 - `brambo123 (@brambo123) <https://github.com/brambo123>`__
@@ -114,10 +108,8 @@ Contributors
 - `Brian Hanifin (@brianhanifin) <https://github.com/brianhanifin>`__
 - `brianrjones69 (@brianrjones69) <https://github.com/brianrjones69>`__
 - `buddydvd (@buddydvd) <https://github.com/buddydvd>`__
-- `bulburDE (@bulburDE) <https://github.com/bulburDE>`__
 - `buxtronix (@buxtronix) <https://github.com/buxtronix>`__
 - `bvansambeek (@bvansambeek) <https://github.com/bvansambeek>`__
-- `bwente (@bwente) <https://github.com/bwente>`__
 - `Carlos Gustavo Sarmiento (@carlos-sarmiento) <https://github.com/carlos-sarmiento>`__
 - `Carlos Garcia Saura (@CarlosGS) <https://github.com/CarlosGS>`__
 - `Carlos Ruiz (@CarlosRDomin) <https://github.com/CarlosRDomin>`__
@@ -145,14 +137,13 @@ Contributors
 - `Dmitry Berezovsky (@corvis) <https://github.com/corvis>`__
 - `Cougar (@Cougar) <https://github.com/Cougar>`__
 - `Connor Prussin (@cprussin) <https://github.com/cprussin>`__
-- `cretep (@cretep) <https://github.com/cretep>`__
 - `cryptelli (@cryptelli) <https://github.com/cryptelli>`__
 - `Chris Talkington (@ctalkington) <https://github.com/ctalkington>`__
 - `cvwillegen (@cvwillegen) <https://github.com/cvwillegen>`__
+- `cwitting (@cwitting) <https://github.com/cwitting>`__
 - `Alex Solomaha (@CyanoFresh) <https://github.com/CyanoFresh>`__
 - `Luar Roji (@cyberplant) <https://github.com/cyberplant>`__
 - `d-two (@d-two) <https://github.com/d-two>`__
-- `d3wy (@d3wy) <https://github.com/d3wy>`__
 - `Dale Higgs (@dale3h) <https://github.com/dale3h>`__
 - `damanti-me (@damanti-me) <https://github.com/damanti-me>`__
 - `Daniel Bjørnbakk (@danibjor) <https://github.com/danibjor>`__
@@ -174,9 +165,8 @@ Contributors
 - `David Buezas (@dbuezas) <https://github.com/dbuezas>`__
 - `dckiller51 (@dckiller51) <https://github.com/dckiller51>`__
 - `Debashish Sahu (@debsahu) <https://github.com/debsahu>`__
-- `declanshanaghy (@declanshanaghy) <https://github.com/declanshanaghy>`__
+- `Dek Shanaghy (@declanshanaghy) <https://github.com/declanshanaghy>`__
 - `definitio (@definitio) <https://github.com/definitio>`__
-- `deftdawg (@deftdawg) <https://github.com/deftdawg>`__
 - `Christiaan Blom (@Deinara) <https://github.com/Deinara>`__
 - `Rsan (@deltazerorsan) <https://github.com/deltazerorsan>`__
 - `Mickaël Le Baillif (@demikl) <https://github.com/demikl>`__
@@ -192,8 +182,6 @@ Contributors
 - `Mark  (@Diramu) <https://github.com/Diramu>`__
 - `Dirk Heinke (@DirkHeinke) <https://github.com/DirkHeinke>`__
 - `Dirk Jahnke (@dirkj) <https://github.com/dirkj>`__
-- `dj-bauer (@dj-bauer) <https://github.com/dj-bauer>`__
-- `djtef (@djtef) <https://github.com/djtef>`__
 - `Marcos Pérez Ferro (@djwmarcx) <https://github.com/djwmarcx>`__
 - `Dan Mannock (@dmannock) <https://github.com/dmannock>`__
 - `Dmitriy Lopatko (@dmitriy5181) <https://github.com/dmitriy5181>`__
@@ -210,7 +198,7 @@ Contributors
 - `DrRob (@DrRob) <https://github.com/DrRob>`__
 - `Daniel Müller (@dtmuller) <https://github.com/dtmuller>`__
 - `dubit0 (@dubit0) <https://github.com/dubit0>`__
-- `Sergey V. DUDANOV (@dudanov) <https://github.com/dudanov>`__
+- `Sergey Dudanov (@dudanov) <https://github.com/dudanov>`__
 - `Duncan Findlay (@duncf) <https://github.com/duncf>`__
 - `dyarkovoy (@dyarkovoy) <https://github.com/dyarkovoy>`__
 - `Dimitris Zervas (@dzervas) <https://github.com/dzervas>`__
@@ -218,6 +206,7 @@ Contributors
 - `Ermanno Baschiera (@ebaschiera) <https://github.com/ebaschiera>`__
 - `Robert Resch (@edenhaus) <https://github.com/edenhaus>`__
 - `Niclas Larsson (@edge90) <https://github.com/edge90>`__
+- `Eduardo Pérez (@eduperez) <https://github.com/eduperez>`__
 - `Eenoo (@Eenoo) <https://github.com/Eenoo>`__
 - `Eli Fidler (@efidler) <https://github.com/efidler>`__
 - `Erwin Kooi (@egeltje) <https://github.com/egeltje>`__
@@ -314,6 +303,7 @@ Contributors
 - `Yang Hau (@HowJMay) <https://github.com/HowJMay>`__
 - `Antonio Vanegas (@hpsaturn) <https://github.com/hpsaturn>`__
 - `hreintke (@hreintke) <https://github.com/hreintke>`__
+- `Jan Hubík (@hubikj) <https://github.com/hubikj>`__
 - `Huub Eikens (@huubeikens) <https://github.com/huubeikens>`__
 - `Petr Urbánek (@HyperReap) <https://github.com/HyperReap>`__
 - `Arjan Filius (@iafilius) <https://github.com/iafilius>`__
@@ -322,7 +312,7 @@ Contributors
 - `igg (@igg) <https://github.com/igg>`__
 - `Petko Bordjukov (@ignisf) <https://github.com/ignisf>`__
 - `ikatkov (@ikatkov) <https://github.com/ikatkov>`__
-- `Michael (@imeekle) <https://github.com/imeekle>`__
+- `imeekle (@imeekle) <https://github.com/imeekle>`__
 - `imgbot[bot] (@imgbot[bot]) <https://github.com/imgbot[bot]>`__
 - `Lorenzo Ortiz (@Infinitte) <https://github.com/Infinitte>`__
 - `irtimaled (@irtimaled) <https://github.com/irtimaled>`__
@@ -342,6 +332,7 @@ Contributors
 - `James Callaghan (@jcallaghan) <https://github.com/jcallaghan>`__
 - `Josh Willox (@jcwillox) <https://github.com/jcwillox>`__
 - `jddonovan (@jddonovan) <https://github.com/jddonovan>`__
+- `JeeCee1 (@JeeCee1) <https://github.com/JeeCee1>`__
 - `jeff-h (@jeff-h) <https://github.com/jeff-h>`__
 - `Jeffrey Borg (@jeffborg) <https://github.com/jeffborg>`__
 - `Jeff Rescignano (@JeffResc) <https://github.com/JeffResc>`__
@@ -364,7 +355,7 @@ Contributors
 - `Jonathan Adams (@jonathanadams) <https://github.com/jonathanadams>`__
 - `Jonathan Treffler (@JonathanTreffler) <https://github.com/JonathanTreffler>`__
 - `JonnyaiR (@jonnyair) <https://github.com/jonnyair>`__
-- `Joppy (@JoppyFurr) <https://github.com/JoppyFurr>`__
+- `Joppy Furr (@JoppyFurr) <https://github.com/JoppyFurr>`__
 - `Joshua Spence (@joshuaspence) <https://github.com/joshuaspence>`__
 - `Joscha Wagner (@jowgn) <https://github.com/jowgn>`__
 - `jsuanet (@jsuanet) <https://github.com/jsuanet>`__
@@ -401,7 +392,7 @@ Contributors
 - `krahabb (@krahabb) <https://github.com/krahabb>`__
 - `Kodey Converse (@krconv) <https://github.com/krconv>`__
 - `KristopherMackowiak (@KristopherMackowiak) <https://github.com/KristopherMackowiak>`__
-- `kroimon (@kroimon) <https://github.com/kroimon>`__
+- `Stefan Rado (@kroimon) <https://github.com/kroimon>`__
 - `krunkel (@krunkel) <https://github.com/krunkel>`__
 - `Kendell R (@KTibow) <https://github.com/KTibow>`__
 - `Jakub Šimo (@kubik369) <https://github.com/kubik369>`__
@@ -413,7 +404,8 @@ Contributors
 - `Steffen Weinreich (@lairsdragon) <https://github.com/lairsdragon>`__
 - `Fredrik Lindqvist (@Landrash) <https://github.com/Landrash>`__
 - `Laszlo Gazdag (@lazlyhu) <https://github.com/lazlyhu>`__
-- `lcavalli (@lcavalli) <https://github.com/lcavalli>`__
+- `Luca Cavalli (@lcavalli) <https://github.com/lcavalli>`__
+- `Craig Fletcher (@leakypixel) <https://github.com/leakypixel>`__
 - `Benny de Leeuw (@leeuwte) <https://github.com/leeuwte>`__
 - `Riku Lindblad (@lepinkainen) <https://github.com/lepinkainen>`__
 - `Lerosen (@Lerosen) <https://github.com/Lerosen>`__
@@ -432,7 +424,7 @@ Contributors
 - `Lewis Juggins (@lwis) <https://github.com/lwis>`__
 - `Alex Peters (@Lx) <https://github.com/Lx>`__
 - `Michael Klamminger (@m1ch) <https://github.com/m1ch>`__
-- `M95D (@M95D) <https://github.com/M95D>`__
+- `Marius Dinu (@M95D) <https://github.com/M95D>`__
 - `Marc-Antoine Courteau (@macourteau) <https://github.com/macourteau>`__
 - `Massimiliano Ravelli (@madron) <https://github.com/madron>`__
 - `Alexandre-Jacques St-Jacques (@Maelstrom96) <https://github.com/Maelstrom96>`__
@@ -494,7 +486,7 @@ Contributors
 - `monkeyclass (@monkeyclass) <https://github.com/monkeyclass>`__
 - `Moritz Glöckl (@moritzgloeckl) <https://github.com/moritzgloeckl>`__
 - `Matthew Pettitt (@mpettitt) <https://github.com/mpettitt>`__
-- `Sam Hughes (@MrEditor97) <https://github.com/MrEditor97>`__
+- `MrEditor97 (@MrEditor97) <https://github.com/MrEditor97>`__
 - `Simon Sasburg (@MrHacky) <https://github.com/MrHacky>`__
 - `Mariusz Kryński (@mrk-its) <https://github.com/mrk-its>`__
 - `Ryan Matthews (@mrrsm) <https://github.com/mrrsm>`__
@@ -552,11 +544,11 @@ Contributors
 - `onde2rock (@onde2rock) <https://github.com/onde2rock>`__
 - `Oscar Bolmsten (@oscar-b) <https://github.com/oscar-b>`__
 - `Trammell Hudson (@osresearch) <https://github.com/osresearch>`__
-- `Otamay (@Otamay) <https://github.com/Otamay>`__
+- `Mauri (@Otamay) <https://github.com/Otamay>`__
 - `Otto Winter (@OttoWinter) <https://github.com/OttoWinter>`__
 - `Ben Owen (@owenb321) <https://github.com/owenb321>`__
 - `Oxan van Leeuwen (@oxan) <https://github.com/oxan>`__
-- `Pack3tL0ss (@Pack3tL0ss) <https://github.com/Pack3tL0ss>`__
+- `Wade (@Pack3tL0ss) <https://github.com/Pack3tL0ss>`__
 - `Pablo Clemente Maseda (@paclema) <https://github.com/paclema>`__
 - `Derrick Lyndon Pallas (@pallas) <https://github.com/pallas>`__
 - `Panuruj Khambanonda (PK) (@panuruj) <https://github.com/panuruj>`__
@@ -588,7 +580,7 @@ Contributors
 - `Leandro Puerari (@puerari) <https://github.com/puerari>`__
 - `puuu (@puuu) <https://github.com/puuu>`__
 - `Qc (@qc24) <https://github.com/qc24>`__
-- `Karol Zlot (@qqgg231) <https://github.com/qqgg231>`__
+- `qqgg231 (@qqgg231) <https://github.com/qqgg231>`__
 - `Tommy Jonsson (@quazzie) <https://github.com/quazzie>`__
 - `Quentin Stafford-Fraser (@quentinsf) <https://github.com/quentinsf>`__
 - `Quinn Hosler (@quinnhosler) <https://github.com/quinnhosler>`__
@@ -664,6 +656,7 @@ Contributors
 - `Luca Zimmermann (@soundstorm) <https://github.com/soundstorm>`__
 - `Sourabh Jaiswal (@sourabhjaiswal) <https://github.com/sourabhjaiswal>`__
 - `Philip Allgaier (@spacegaier) <https://github.com/spacegaier>`__
+- `spacemanspiff2007 (@spacemanspiff2007) <https://github.com/spacemanspiff2007>`__
 - `spattinson (@spattinson) <https://github.com/spattinson>`__
 - `Sean Brogan (@spbrogan) <https://github.com/spbrogan>`__
 - `Stephan Peijnik-Steinwender (@speijnik) <https://github.com/speijnik>`__
@@ -721,7 +714,7 @@ Contributors
 - `Tim Savage (@timsavage) <https://github.com/timsavage>`__
 - `Max Efremov (@Tmin10) <https://github.com/Tmin10>`__
 - `Snōwball (@tobias-) <https://github.com/tobias->`__
-- `Philipp Tölke (@toelke) <https://github.com/toelke>`__
+- `Philipp Riederer (@toelke) <https://github.com/toelke>`__
 - `Tom Brien (@TomBrien) <https://github.com/TomBrien>`__
 - `TomFahey (@TomFahey) <https://github.com/TomFahey>`__
 - `Tommy Kihlstrøm (@tomludd) <https://github.com/tomludd>`__
@@ -731,7 +724,7 @@ Contributors
 - `tony (@tony-fav) <https://github.com/tony-fav>`__
 - `David Kiliani (@torfbolt) <https://github.com/torfbolt>`__
 - `Torwag (@torwag) <https://github.com/torwag>`__
-- `Felix Eckhofer (@tribut) <https://github.com/tribut>`__
+- `Felix E (@tribut) <https://github.com/tribut>`__
 - `Tobias (@tripplet) <https://github.com/tripplet>`__
 - `Troon (@Troon) <https://github.com/Troon>`__
 - `Olli Salonen (@trsqr) <https://github.com/trsqr>`__
@@ -746,10 +739,12 @@ Contributors
 - `TVDLoewe (@TVDLoewe) <https://github.com/TVDLoewe>`__
 - `Thorsten von Eicken (@tve) <https://github.com/tve>`__
 - `Tyler Menezes (@tylermenezes) <https://github.com/tylermenezes>`__
-- `ukewea (@ukewea) <https://github.com/ukewea>`__
+- `wuuker (@ukewea) <https://github.com/ukewea>`__
 - `Vc (@Valcob) <https://github.com/Valcob>`__
 - `Nad (@valordk) <https://github.com/valordk>`__
+- `André Lademann (@vergissberlin) <https://github.com/vergissberlin>`__
 - `Víctor Ferrer García (@vicfergar) <https://github.com/vicfergar>`__
+- `VitaliyKurokhtin (@VitaliyKurokhtin) <https://github.com/VitaliyKurokhtin>`__
 - `voibit (@voibit) <https://github.com/voibit>`__
 - `Xuming Feng (@voicevon) <https://github.com/voicevon>`__
 - `vxider (@Vxider) <https://github.com/Vxider>`__
@@ -762,6 +757,7 @@ Contributors
 - `Werner Beroux (@wernight) <https://github.com/wernight>`__
 - `wifwucite (@wifwucite) <https://github.com/wifwucite>`__
 - `wilberforce (@wilberforce) <https://github.com/wilberforce>`__
+- `William Charlton (@willwill2will54) <https://github.com/willwill2will54>`__
 - `Wilmar den Ouden (@wilmardo) <https://github.com/wilmardo>`__
 - `Emil Hesslow (@WizKid) <https://github.com/WizKid>`__
 - `WJCarpenter (@wjcarpenter) <https://github.com/wjcarpenter>`__
@@ -770,7 +766,7 @@ Contributors
 - `workingmanrob (@workingmanrob) <https://github.com/workingmanrob>`__
 - `Wojtek Strzalka (@wstrzalka) <https://github.com/wstrzalka>`__
 - `Mike (@xsnoopy) <https://github.com/xsnoopy>`__
-- `Yaroslav (@Yarikx) <https://github.com/Yarikx>`__
+- `Yaroslav Heriatovych (@Yarikx) <https://github.com/Yarikx>`__
 - `Marcin Jaworski (@yawor) <https://github.com/yawor>`__
 - `ychieux (@ychieux) <https://github.com/ychieux>`__
 - `Pavel (@yekm) <https://github.com/yekm>`__
@@ -783,8 +779,7 @@ Contributors
 - `david reid (@zathras777) <https://github.com/zathras777>`__
 - `ZJY (@zhangjingye03) <https://github.com/zhangjingye03>`__
 - `San (@zhujunsan) <https://github.com/zhujunsan>`__
-- `Zoltant7 (@Zoltant7) <https://github.com/Zoltant7>`__
 - `ZTX18 (@ZTX18) <https://github.com/ZTX18>`__
 - `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
 
-*This page was last updated January 19, 2022.*
+*This page was last updated January 25, 2022.*

images/high-voltage-warning.svg

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Sodipodi ("http://www.sodipodi.com/") -->
+<svg id="svg602" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" xml:space="preserve" height="590.51" width="704.26" version="1.0" y="0" x="0" xmlns:cc="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata id="metadata2230"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/></cc:Work></rdf:RDF></metadata><path id="path634" stroke-linejoin="round" d="m666.48 585.05l-634.18 0.46c-24.787 0.02-35.217-24.94-20.626-49.36l304.68-509.93c17.4-28.298 49.66-28.606 67.06 0.955l308.18 508.52c16.95 24.27 4.62 49.78-25.11 49.35z" fill-rule="evenodd" stroke="#ffe600" stroke-width="10"/><path id="path609" fill-rule="evenodd" fill="#ffe600" d="m507.62 360.36l89.41 153.81-307.47 2.61-180.25-1.77 150-262.2 90.84-152.05 157.47 259.6z"/><path id="path615" fill-rule="evenodd" d="m331.93 194.79l-76.78 187.8 107.49-36.61-37.8 140.56 80.32-172.45-114.57 35.43 82.68-155.91-41.34 1.18z"/><path id="path617" fill-rule="evenodd" d="m316.57 434.56l9.45 57.88 41.34-48.43-29.53 7.09-21.26-16.54z"/></svg>

index.rst

@@ -23,17 +23,17 @@ ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configu
             <ul>
                 <li>
                     <a class="reference" href="/guides/getting_started_hassio.html">
-                        ESPHome Dashboard
+                        from Home Assistant
                     </a>
                 </li>
                 <li>
                     <a class="reference" href="/guides/getting_started_command_line.html">
-                        Command Line Interface
+                        using the command line
                     </a>
                 </li>
                 <li>
                     <a class="reference" href="/guides/migrate_sonoff_tasmota.html">
-                        Migrating from Tasmota
+                        by migrating from Tasmota
                     </a>
                 </li>
             </ul>
@@ -689,6 +689,7 @@ Cookbook
     ESP32 Water Leak Detector, cookbook/leak-detector-m5stickC, leak-detector-m5stickC_main_index.jpg
     ESP32 BLE iTag Button, cookbook/ble_itag, esp32_ble_itag.jpg
     IAQ (Indoor Air Quality) Board, cookbook/iaq_board, iaq_board2.jpg
+    TUYA Smart Life RGBW Controller, cookbook/tuya_rgbw, ../cookbook/images/tuya_rgbw.jpg
     Custom UART Text Sensor, cookbook/uart_text_sensor, language-cpp.svg
     IWOOLE Table Lamp, cookbook/iwoole_rgbw_table_lamp, iwoole_rgbw_table_lamp.png
     EPEVER Tracer, cookbook/tracer-an, tracer-an.jpg

requirements.txt

@@ -1 +1,2 @@
 sphinx==4.3.2
+sphinx-autobuild==2021.3.14