Esphome flasher deprecated (#3717)

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

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/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::