ESPHome OTA Updates

ESPHome’s Over-The-Air (OTA) platform allows you to remotely install modified/updated firmware binaries onto your ESPHome devices over their network interface (Wi-Fi / Ethernet / Thread).

This platform is used by both the ESPHome dashboard as well as the command line interface (CLI) (via esphome run ... ) to install firmware onto supported devices.

In addition to OTA updates, ESPHome also supports a “safe mode” to help with recovery if/when updates don’t work as expected. This is automatically enabled by this component, but it may be disabled if desired. See Safe Mode for details.

# Example configuration entry
ota:
  - platform: esphome
    password: !secret ota_password

Configuration variables

password (Optional, string): The password to use for updates.
allow_partition_access (Optional, boolean): Only on esp32. Allow updating more partition types. Used for updating the partition table and the bootloader. Defaults to false.

IMPORTANT

Always use strong, unique passwords for OTA updates. See the Security Best Practices guide for more information.

port (Optional, int): The port to use for OTA updates. Defaults:
- 3232 for the ESP32
- 8266 for the ESP8266
- 2040 for the RP2040
- 8892 for Beken chips
- 8082 for the host platform
id (Optional, ID): Manually specify the ID used for code generation.
version (Optional, int): Version of OTA protocol to use. Version 2 is more stable. To downgrade to legacy ESPHome, the device should be updated with OTA version 1 first. Defaults to 2.
All automations supported by Ota.

NOTE

After a serial upload, ESP8266 modules must be reset before OTA updates will work. If you attempt to perform an OTA update and receive the error message Bad Answer: ERR: ERROR[11]: Invalid bootstrapping, the ESP module/board must be power-cycled.

Updating the Password

Changing an Existing Password

Since the configured password is used for both compiling and uploading, the regular esphome run <file> command won’t work. This issue can be worked around by executing the operations separately with an on_boot trigger:

esphome:
  on_boot:
    - lambda: |-
        id(my_ota).set_auth_password("New password");

ota:
  - platform: esphome
    id: my_ota
    password: "Old password"

The “id: my_ota” in the OTA block is important. This is referenced in the lambda. After this trick has been used to change the password, the on_boot trigger may be removed and the old password replaced with the new password in the ota: section.

Adding a Password

If OTA is already enabled without a password, simply add a password: line to the existing ota: config block.

Removing a Password

If you know your password but want to remove it, enter an empty string: id(my_ota).set_auth_password(""); instead of changing.
If you no longer know your password and the web server has been activated:
- Remove the OTA password from the configuration
- Build a new image locally.
- Upload it via the web_server OTA platform; either through the device’s web interface or by running esphome upload <config.yaml> --ota-platform web_server (see the Web Server OTA CLI usage section).

Updating the partition table on ESP32

On the ESP32 it is possible to modify the partition table with an OTA update. This feature can be used to update devices that can’t be flashed via serial and have an old partition table with a small NVS partition. It can also be used to convert devices running Tasmota to ESPHome. Before you can update the partition table you need to add the option allow_partition_access: true to the config and install it to your device.

ota:
  - platform: esphome
    allow_partition_access: true

CAUTION

There is a risk of bricking the device if the power is interrupted or the ESP is reset during a partition table update, requiring serial flashing to repair it. Make sure you have a stable power supply. The update is usually completed within less than 15 seconds after running the esphome upload command.

Open the ESPHome logs for detailed information about potential errors. To perform the partition table update you can run the following command:

esphome upload --partition-table name-of-your-config.yaml

To upload a custom partition table from a CSV file, you can run the commands below. gen_esp32part.py is part of ESP-IDF and can be found here.

python3 gen_esp32part.py partitions.csv partitions.bin
esphome upload --partition-table --file partitions.bin name-of-your-config.yaml

CAUTION

When converting a Tasmota ESP32 device to ESPHome, it is required to add allow_partition_access: true on the first ESPHome firmware you upload to the device. Regular OTA updates will not work until the partition table update is completed.

Updating the bootloader on ESP32

On the ESP32 it is possible to update the bootloader with an OTA update. This is useful on devices that can’t be flashed via serial and need a newer bootloader, for example to enable OTA rollback or SRAM1 as IRAM. Before you can update the bootloader you need to add the option allow_partition_access: true to the config and install it to your device.

ota:
  - platform: esphome
    allow_partition_access: true

CAUTION

There is a risk of soft-bricking the device if the power is interrupted or the ESP is reset during the bootloader update, requiring serial flashing to recover it. Make sure you have a stable power supply, and be ready to reflash via USB if it fails.

Open the ESPHome logs for detailed information about potential errors. To perform the bootloader update, run:

esphome upload --bootloader name-of-your-config.yaml

Without --file, the bootloader image from the most recent compile is used (build/bootloader/bootloader.bin for native ESP-IDF, or .pioenvs/<name>/bootloader.bin for PlatformIO).

To upload a custom bootloader binary, run:

esphome upload --bootloader --file bootloader.bin name-of-your-config.yaml

ESPHome OTA Updates

Configuration variables

Updating the Password

Changing an Existing Password

Adding a Password

Removing a Password

Updating the partition table on ESP32

Updating the bootloader on ESP32

See Also