Skip to content

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

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 device needs to be connected to your PC with a UART-TTL adapter. Refer to chip connection guides to learn how to connect your device.

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

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

Using ltchiptool (wired, via UART)

You can use the ltchiptool GUI or CLI to manually flash the firmware. Grab the firmware.uf2 file from the build directory. Then, follow the ltchiptool usage guide to flash it to the device.

Tip

The UF2 file may have a different name, depending on the project you're building. Usually it's best to grab the latest (sorted by date) file with UF2 extension from the build directory.

Converting devices with tuya-cloudcutter

Note

This currently applies to BK7231T and BK7231N only. tuya-cloudcutter can't be used for other chips.

Grab the image_bk7231x_app.ota.ug.bin file from the build directory - take care to choose the correct file. It must have "OTA" and "UG" in its name.

Next, refer to Using tuya-cloudcutter guide.

Migrating from OpenBeken (OTA)

OpenBeken is a custom, Tasmota-like firmware for non-ESP chips. Currently, this part of the guide applies to BK7231 only, as that's the only chip supported both by LT and OBK.

OBK is compatible with standard Beken OTA packages, but the web panel does a filename check to prevent chip type mismatch. Grab the image_bk7231t_app.ota.rbl file from build directory (note: without "UG" in the name!), rename it to something like OpenBK7231T_esphome.rbl (change T to N depending on the chip type), and drop it on the OTA panel.

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.