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 (Wi-Fi or Ethernet) interface.

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.

  • 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

  • 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 Over-the-Air Updates.

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.

    • Execute the OTA update directly via the ESP web server.

See Also