Esphome flasher deprecated (#3717)

This commit is contained in:
H. Árkosi Róbert 2024-04-14 23:07:00 +02:00 committed by GitHub
parent 9c65aae94a
commit 5c254fb842
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 94 additions and 48 deletions

View File

@ -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

View File

@ -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.
.. note::
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``
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!!
-------------------------------

View File

@ -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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 149 KiB

View File

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