Merge branch 'current' into beta

changelog/v1.9.0.rst

@@ -30,7 +30,7 @@ awesome things with DIY hardware!
 
 The features I'm particularly excited about are:
 
-* :ref:`esphomeflasher <esphome-flasher>` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
+* ``esphomeflasher`` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
   No problem, esphomeflasher is a tool designed to make that super easy. Just let esphomeyaml generate the binary and flash
   from your PC.
 * :doc:`Over-the-Air Updates </components/ota>` have been completely re-written to make them a lot more
@@ -76,7 +76,7 @@ New Features
 
 - esphomelib now has a new tool: `esphomeflasher <https://github.com/esphome/esphome-flasher>`__ to simplify
   flashing on Windows/MacOS machines **without having to install esphomeyaml**. So if esphomeyaml for some reason
-  can't find your USB port, you now can use the esphomeflasher app. See :ref:`esphome-flasher`.
+  can't find your USB port, you now can use the esphomeflasher app. See ``esphomeflasher``.
 
 - ESP8266s now save the states of lights/switches/... internally and restores them on boot.
   Additionally, esphomelib can now operate in fully offline mode if your WiFi network goes down

components/display/index.rst

@@ -45,6 +45,9 @@ this behavior by setting ``auto_clear_enabled: false``.
 In the lambda, you can write code like in any :ref:`lambda <config-lambda>` in ESPHome. Display
 lambdas are additionally passed a variable called ``it`` which represents the rendering engine object.
 
+.. figure:: images/display_rendering_line.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
@@ -74,8 +77,10 @@ the rendering engine is always first specify the ``x`` coordinate and then the `
 Basic Shapes
 ------------
 
-Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles
-and circles:
+Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles, circles or even polygons:
+
+.. figure:: images/display_rendering_shapes.png
+    :align: center
 
 .. code-block:: yaml
 
@@ -85,31 +90,27 @@ and circles:
         lambda: |-
           // Draw a line from [0,0] to [100,50]
           it.line(0, 0, 100, 50);
-          // Draw an angled line from [0,0] at 45° with a length of 30
-          it.line_at_angle(0, 0, 45, 30);
-          // Draw an angled line from [0,0] at 30° with a start radius of 10 and stop radius of 20
-          it.line_at_angle(0, 0, 30, 10, 20);
-          // Draw the outline of a rectangle with the top left at [50,60], a width of 30 and a height of 42
-          it.rectangle(50, 60, 30, 42);
-          // Draw the same rectangle, but this time filled.
-          it.filled_rectangle(50, 60, 30, 42);
+          // Draw the outline of a rectangle with the top left at [5,20], a width of 30 and a height of 42
+          it.rectangle(5, 20, 30, 42);
+          // Draw the same rectangle a few pixels apart, but this time filled
+          it.filled_rectangle(40, 40, 30, 42);
 
-          // Circles! Let's draw one with the center at [25,25] and a radius of 10
-          it.circle(25, 25, 10);
+          // Circles! Let's draw one with the center at [20,40] and a radius of 10
+          it.circle(20, 40, 10);
           // ... and the same thing filled again
-          it.filled_circle(25, 25, 10);
+          it.filled_circle(20, 75, 10);
 
           // Triangles... Let's draw the outline of a triangle from the [x,y] coordinates of its three points
-          // [25,5], [5,25], [50,50]
-          it.triangle(25, 5, 5, 25, 50, 50);
+          // [25,5], [100,5], [80,25]
+          it.triangle(25, 5, 100, 5, 80, 25);
           // and a filled triangle !
-          it.filled_triangle(125, 5, 105, 25, 150, 50);
+          it.filled_triangle(115, 5, 95, 25, 125, 70);
 
-          // Regular Polygons? Let's draw the outline of a pointy-topped hexagon inscribed in a circle 
-          // centered on [x1=100,y1=100] with a radius of 50
-          it.regular_polygon(100, 100, 50, EDGES_HEXAGON);
-          // and a filled flat-topped octagon!
-          it.filled_regular_polygon(200, 200, 50, EDGES_OCTAGON, VARIATION_FLAT_TOP);
+          // Regular Polygons? Let's draw a filled, pointy-topped hexagon inscribed in a circle
+          // centered on [170,45] with a radius of 20
+          it.filled_regular_polygon(170, 45, 20, EDGES_HEXAGON);
+          // and the outline of flat-topped octagon around it!
+          it.regular_polygon(170, 45, 40, EDGES_OCTAGON, VARIATION_FLAT_TOP);
           // Need to rotate the polygon, or retrieve the coordinates of its vertices? Check the API!
 
 All the above methods can optionally also be called with an argument at the end which specifies in which
@@ -121,33 +122,35 @@ color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color
       - platform: ...
         # ...
         lambda: |-
-          // Turn the whole display on.
+          // Turn the whole display on
           it.fill(COLOR_ON);
-          // Turn the whole display off.
+          // Turn the whole display off
           it.fill(COLOR_OFF);
 
           // Turn a single pixel off at [50,60]
           it.draw_pixel_at(50, 60, COLOR_OFF);
 
-          // Turn off a whole display portion.
-          it.rectangle(50, 50, 30, 42, COLOR_OFF);
-
 For color displays (e.g. TFT displays), you can use the Color class.
 
+.. figure:: images/display_rendering_colors.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
       - platform: ...
         # ...
         lambda: |-
+          auto black = Color(0, 0, 0);
           auto red = Color(255, 0, 0);
           auto green = Color(0, 255, 0);
           auto blue = Color(0, 0, 255);
           auto white = Color(255, 255, 255);
-          it.rectangle(20, 50, 30, 30, white);
-          it.rectangle(25, 55, 30, 30, red);
-          it.rectangle(30, 60, 30, 30, green);
-          it.rectangle(35, 65, 30, 30, blue);
+          it.filled_circle(20, 32, 15, black);
+          it.filled_circle(40, 32, 15, red);
+          it.filled_circle(60, 32, 15, green);
+          it.filled_circle(80, 32, 15, blue);
+          it.filled_circle(100, 32, 15, white);
 
 Additionally, you have access to two helper methods which will fetch the width and height of the display:
 
@@ -160,6 +163,8 @@ Additionally, you have access to two helper methods which will fetch the width a
           // Draw a circle in the middle of the display
           it.filled_circle(it.get_width() / 2, it.get_height() / 2, 20);
 
+          // Turn off bottom half of the screen
+          it.filled_rectangle(0, it.get_height()/2, it.get_width(), it.get_height()/2, COLOR_OFF);
 
 You can view the full API documentation for the rendering engine in the "API Reference" in the See Also section.
 
@@ -222,6 +227,10 @@ In case of fonts rendered at higher bit depths, the background color has to be s
           // Syntax is always: it.print(<x>, <y>, <font>, [color=COLOR_ON], [align], <text>, [color=COLOR_OFF]);
           it.print(0, 0, id(my_font_with_icons), COLOR_ON, TextAlign::CENTER, "Just\U000f05d4here. Already\U000F02D1this.", COLOR_OFF);
 
+
+.. figure:: images/display_rendering_text.png
+    :align: center
+
 .. _display-printf:
 
 Formatted Text
@@ -461,13 +470,8 @@ memory at the time the sensor updates and will be lost when the device reboots.
 
 Examples:
 
-.. figure:: images/graph_screen.png
+.. figure:: images/display_rendering_graph.png
     :align: center
-    :width: 60.0%
-
-.. figure:: images/graph_dualtrace.png
-    :align: center
-    :width: 60.0%
 
 Graph component with options for grids, border and line-types.
 

components/sensor/index.rst

@@ -603,7 +603,7 @@ To prevent values from being published, return ``{}``:
 .. code-block:: yaml
 
     filters:
-      - lambda: !lambda |-
+      - lambda: |-
           if (x < 10) return {};
           return x-10;
 

components/sensor/xiaomi_ble.rst

@@ -8,6 +8,12 @@ Xiaomi Mijia BLE Sensors
 
 The ``xiaomi_ble`` sensor platform lets you track the output of Xiaomi Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component will track, for example, the temperature, humidity, moisture, conductivity, illuminance, formaldehyde, mosquito tablet and battery level of the device every time the sensor sends out a BLE broadcast. Contrary to other implementations, ``xiaomi_ble`` listens passively to advertisement packets and does not pair with the device. Hence ESPHome has no impact on battery life. Thus, if you only use such sensors, you can safely set ``scan_parameters.active: false`` in ``esp32_ble_tracker`` configuration, to save from spamming your RF environment with useless scan requests.
 
+
+.. note::
+
+    You may alternatively use ESPHome's :doc:`/components/bluetooth_proxy` component to forward sensor data to Home Assistant and have Mija devices configured using its own Mija BLE component. This should work for the devices flashed with `PVVX MiThermometer <https://github.com/pvvx/ATC_MiThermometer>`__ custom firmware, as well as the regular, stock firmware.
+
+
 Supported Devices
 -----------------
 
@@ -642,10 +648,6 @@ Security considerations
 
 You should at least protect your sensors with a custom pairing PIN code. Choose a method employing bindkey in order to use encrypted communication over the air.
 
-.. note::
-
-    Devices flashed with `PVVX MiThermometer <https://github.com/pvvx/ATC_MiThermometer>`__ custom firmware also support the `BTHome protocol <https://bthome.io/>`__ which can be used in conjunction with ESPHome's :doc:`/components/bluetooth_proxy` component to forward sensor data to Home Assistant.
-
 
 See Also
 --------

guides/diy.rst

@@ -92,6 +92,7 @@ Custom Components & Code
 - `Custom esp32 media player and notifier <https://www.printables.com/model/327708-esphome-nodemcu-esp32-media-player>`__ by :ghuser:`rananna`
 - `Blauberg recuperator S22 controller replacement <https://github.com/Benas09/Blauberg_S22>`__ by :ghuser:`Benas09`
 - `Rheem Econet Water Heater and Furnace Controller <https://github.com/esphome-econet/esphome-econet>`__ by `ESPHome-econet <https://github.com/esphome-econet>`__
+- `Garage Door Opener with position control using a relay and one or two reed sensors <https://github.com/tronikos/esphome-gdo>`__ by :ghuser:`tronikos`
 - `Medisana BS440 (and propably more scales) <https://github.com/bwynants/weegschaal>`__ by `bwynants <https://github.com/bwynants>`__
 
 Sample Configurations

guides/faq.rst

@@ -73,48 +73,54 @@ Tips for using ESPHome
 .. |include| replace:: ``!include``
 .. _include: https://www.home-assistant.io/docs/configuration/splitting_configuration/
 
-.. _esphome-flasher:
-
 I can't get flashing over USB to work.
 --------------------------------------
 
-ESPHome depends on the operating system the tool is running on to recognize
-the ESP. This can sometimes fail. Common causes are that you did not install
-the drivers (see note below) or you are trying to upload from a Docker container
-and did not mount the ESP device into your container using ``--device=/dev/ttyUSB0``.
+.. _esphome-esptool:
 
-Starting with ESPHome 1.9.0, the ESPHome suite provides
-`esphome-flasher <https://github.com/esphome/esphome-flasher>`__, a tool to flash ESPs over USB.
+ESPHome depends on the operating system the tool is running on to recognize the ESP. This can sometimes fail. Common causes are that you may not have the drivers installed (see :ref:`here <esphome-phy-con-drv>`) or you are trying to upload from a Docker container and did not mount the ESP device into your container using ``--device=/dev/ttyUSB0``.
 
 First, you need to get the firmware file to flash. For the Home Assistant add-on based
-installs you can use the ``Manual download`` method (click ``Install`` in the overflow icon with the three dots
-and then select ``Manual download``). For command line based installs you can access the
+installs you can use the ``Manual download`` method of the Dashboard (click ``Install`` in the overflow icon with the three dots
+and then select ``Manual download``). For direct esphome command line based installs you can access the
 file under ``<CONFIG_DIR>/<NODE_NAME>/.pioenvs/<NODE_NAME>/firmware.bin``.
 
-Then, install esphome-flasher by going to the `releases page <https://github.com/esphome/esphome-flasher/releases>`__
-and downloading one of the pre-compiled binaries. Open up the application and select the serial port
-you want to flash to (on windows you can use the "device manager" to check if it's the right one).
+Second, you need to put the ESP in :ref:`programming mode <esphome-phy-con-prg>` while connecting it to your computer.
 
-.. figure:: images/esphomeflasher-ui.png
-    :align: center
-    :width: 80%
 
-Select the firmware binary and finally press "Flash ESP".
+Third, to flash a firmware file downloaded from Home Assistant add-on Dashboard, you can use:
+
+- `ESPHome Web <https://web.esphome.io/>`__ web-based installer, which requires a browser that supports WebSerial, like Google Chrome or Microsoft Edge. Connect the board to your computer, make sure it's detected as a :ref:`serial port <esphome-phy-con-drv>`, and press **Connect**. Give the requested permission in the browser and in the popup box that appears, select the serial device which connects to your ESP. Then press **Install**, and browse for the binary file you downloaded from the Dashboard in the step above. Note that the file will be processed locally, it won't be uploaded to any cloud service.
+- *esptool* `from the GitHub repository <https://github.com/espressif/esptool/releases>`__, package from your distro or install it yourself with ``pip install esptool`` (in case of Linux). 
+
+Before using ``esptool``, make sure you know which serial port your programming adapter is connected to. In Linux use the ``dmesg`` command afer you plug the device into the USB port to see the name of the newly detected serial port. In Windows check the Device Manager to see if a new serial port appears when you plug it in and note the COM number.
+
+Erase flash:
+
+.. code-block:: bash
+
+    esptool --port /dev/ttyUSB0 erase_flash
+
+Program flash with your firmware binary:
+
+.. code-block:: bash
+
+    esptool --port /dev/ttyUSB0 write_flash 0x0 your_node_firmware.bin
 
 .. note::
 
-    If the serial port is not showing up, you might not have the required drivers installed.
-    ESPs usually ship with one of these two UART chips:
+    If you're just seeing ``Connecting....____....`` on the screen and the flashing fails, check for these: 
 
-     * 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>`__
+    - the device name of the port has changed while you were re-plugging it too fast (eg. changed from ``/dev/ttyUSB0`` to ``/dev/ttyUSB1``). 
+    - double check the UART wires are connected correctly if flashing using an external programmer (RX of programmer to TX of the ESP and vice-versa).
+    - for some devices you need to keep ``GPIO0`` and ``GND`` connected at least until flashing has begun.
+    - for some devices you need to power-cycle in programming mode after erasing flash, they don't auto-reset.
+    - it also might be a sign that ESP is defect or cannot be programmed. 
+    
+    If you're in an RF noisy environment or your UART wires are a bit long, flashing can fail during transfer. Don't worry, an ESP won't brick just because of that. Put it again in programming mode and flash with a reduced baudrate for safer transfers:
+    
+    ``esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 your_node_firmware.bin``
 
-.. note::
-
-    If you're just seeing ``Connecting....____....`` on the screen and the flashing fails, that might
-    be a sign that the ESP is defect or cannot be programmed. Please double check the UART wires
-    are connected correctly if flashing using a USB to UART bridge. For some devices you need to
-    keep pressing the BOOT button until flashing has begun (ie. Geekcreit DOIT ESP32 DEVKIT V1).
 
 Help! Something's not working!!
 -------------------------------

guides/getting_started_command_line.rst

@@ -144,10 +144,15 @@ to your docker command to map a local USB device. Docker on Mac will not be able
 
     docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run livingroom.yaml
 
-Now when you go to the Home Assistant "Integrations" screen (under "Configuration" panel), you
+
+.. note::
+
+    Alternatively, you can flash the binary using :ref:`ESPHome Web or esptool <esphome-esptool>`.
+
+Now when you go to the Home Assistant **Integrations** screen (under **Configuration** panel), you
 should see the ESPHome device show up in the discovered section (although this can take up to 5 minutes).
-Alternatively, you can manually add the device by clicking "CONFIGURE" on the ESPHome integration
-and entering "<NODE_NAME>.local" as the host.
+Alternatively, you can manually add the device by clicking **CONFIGURE** on the ESPHome integration
+and entering ``<NODE_NAME>.local`` as the host.
 
 .. figure:: /components/switch/images/gpio-ui.png
     :align: center

guides/made_for_esphome.rst

@@ -37,7 +37,9 @@ For all projects
 - Your project supports adoption via the ``dashboard_import`` feature of ESPHome (see :doc:`Sharing </guides/creators>`). In particular:
     - There are **no** references to secrets or passwords
     - Network configuration must assume defaults (no static IPs or DNS configured)
-    - All configuration is contained within a single YAML file
+    - It **must** compile successfully without any user changes after adopting it.
+    - All configuration is contained within a single YAML file. Fully remote packages are permitted if using ``import_full_config: true``.
+
 - Your product name cannot contain **ESPHome** except in the case of *ending with* **for ESPHome**
 
 When your project matches all requirements of the Made for ESPHome program,

guides/physical_device_connection.rst

@@ -29,31 +29,66 @@ 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.
+have adapter built into the circuit board (and some even have the programmer
+embedded in the MCU, in which case things are a bit easier.
+
+In case you use an external serial programmer connected to RX and TX of the ESP, choose one based
+on CH340 as it's the most reliable and the cheapest one to use for flashing. Programmers based on
+CP2102 or PL2303 are compatible with many devices, but using an external 3.3V supply might be
+necessary for them. 
+
+.. _esphome-phy-con-drv:
+
+Plug in the board or the serial programmer into a free USB port and check if it has been properly detected
+by your computer. The firmware programming tools use a serial interface to communicate with your device. 
+On Windows these interfaces are named ``COM1``, ``COM2``, etc. and on Linux they are named ``/dev/ttyUSB0``,
+``/dev/ttyACM1``, etc. 
 
 .. 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:
+    If it's not showing up as a serial port, you might not have the required drivers
+    installed. The model number you need is engraved on the chip connected to the USB port.
+    ESPs and programmers usually ship with one of these UART chips:
 
-      * 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>`__
+    * CH34x: `driver <https://github.com/nodemcu/nodemcu-devkit/tree/master/Drivers>`__
+    * CP2102: `driver <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`__
+    * PL2303: `driver <https://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41>`__
 
 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).
+- ``+3.3V``, or occasionally ``+5.0V``
+- ``GND``, or ground
+- ``TX`` of programmer to ``RX`` of the ``ESP``
+- ``RX`` of programmer to ``TX`` of the ``ESP``
+- ``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
+The power supplied to the device is one of the most important elements for both flashing
+the device and for stable operation. You must ensure that the device receives sufficient
+power (current AND appropriate voltage level) to properly flash the firmware on the device.
+When using an external ``3.3V`` supply, ensure the ground (``GND``) of both are connected together,
+this ensures a common ground. A PC power supply can be a good source for ``3.3V`` DC power.
+
+.. note::
+
+    Some adapters can be switched between ``3.3V`` and ``5V`` for the data pins, but still provide 5V on the power pin which will irreparably destroy your device. You **MUST** make sure the data (``RX`` and ``TX``) and ``VCC`` pins are set for ``3.3V``.
+
+ESP needs to be put into programming mode or flash mode before the firmware can be uploaded. This is
+done by connecting ``GPIO0`` pin to ``GND`` while the chip is booting. 
+
+.. _esphome-phy-con-prg:
+
+To put the ESP into programming mode:
+
+* Disconnect the USB connection of your board or serial programmer from the computer (to power off your ESP)
+* Bridge ``GPIO0`` and ``GND`` (by pressing the on-board button or connection with a wire)
+* Connect the board or serial programmer to your computer (ensuring ESP powers up)
+* After a few seconds disconnect ``GPIO0`` from ``GND`` (release button or remove the wire connection). On devices that do not provide the ``GPIO0`` connected button, it may be easier to leave the wired bridge in place throughout the entire flashing process (erase & upload). Doing so will not create any problems. After the firmware is uploaded successfully, remove the bridge. This allows the device to boot normally.
+
+You may need to power-cycle the ESP between erasing and uploading the firmware, this can be done by disconnecting and reconnecting, of course with ``GPIO0`` and ``GND`` still connected to each other.
+
+``RX`` and ``TX`` can be sometimes swapped. If programming your board doesn't work the
 first time, try flipping the wires connected to those pins before trying again.
 
 .. warning::