libretiny/docs/flashing/esphome.md

Flashing ESPHome

!!! tip See the Cloudcutter video guide for a complete tutorial on flashing with Cloudcutter and installing LibreTiny-ESPHome. Includes Home Assistant Add-On setup.

ESPHome can be flashed in few different ways, depending on your needs.

!!! abstract All binary files generated by ESPHome will be in .esphome/build/<yourdevice>/.pioenvs/<yourdevice>/. The methods described below may require you to get a file from that directory.

If you're using the GUI (ESPHome Dashboard) this path will be in your `configs/` directory.

This path will be referred to as **build directory**.

Built-in flasher

=== "CLI"

The flasher program built-in LibreTiny is also available for ESPHome.

- use `python -m esphome run yourdevice.yml` to recompile AND upload the firmware
- use `python -m esphome upload yourdevice.yml` to upload without recompiling

<!-- the line below needs to be indented by 4 spaces!!!  -->
{%
	include-markdown "../inc/uart-info.md"
%}

If your device is already running ESPHome, refer to the OTA guide below.

=== "GUI"

The built-in flasher is not yet available in the GUI. Here are your options:

- OTA, using the downloaded UF2 file (if you're already running ESPHome)
- wired (also UF2), using [ltchiptool](tools/ltchiptool.md)
- wirelessly, using tuya-cloudcutter

Read below for more details on each of these methods.

Over-the-Air (OTA)

This method requires having ESPHome already installed on your device.

• If you've added the Web Server component, navigate to the device's IP address (or .local name) in your web browser. Grab firmware.uf2 from the build directory and drop it on the "OTA Update" field.
• You can also use ESPHome CLI to flash via OTA. Add a --device argument to the command, as such: python -m esphome upload yourdevice.yml --device yourdevice.local

{% include-markdown "../inc/uart-ltchiptool.md" %}

{% include-markdown "../inc/ota-cloudcutter.md" %}

{% include-markdown "../inc/ota-openbeken.md" %}

Migrating from ESPHome to OpenBeken

ESPHome is only compatible with UF2 OTA packages, which OpenBeken doesn't provide. You need to create an UF2 package manually, using ltchiptool (see ltchiptool#7 for more info). Grab an .RBL file from OpenBeken Releases page, and run this command:

ltchiptool uf2 write -b generic-bk7231n-qfn32-tuya -o OpenBeken.uf2 "OpenBK7231N_1.17.205.rbl=device:download"

This will create OpenBeken.uf2 file that you can upload on the ESPHome web server dashboard page. Pay attention to the chip selection - incorrectly built UF2 file may brick your device! Make sure to download the right .RBL file of OpenBeken, and to choose the correct board (-b) parameter.