OTA Update Component

With the OTA (Over The Air) update component you can upload your firmware binaries to your node without having to use a USB cable for uploads. ESPHome natively supports this through its run and upload helper scripts.

ESPHome also has an “OTA safe mode”. If for some reason your node gets into a boot loop, ESPHome will automatically try to detect this and will go over into a safe mode after the configured unsuccessful boot attempts (Defaults to 10). In that mode, all components are disabled and only Serial Logging + Network(WiFi or Ethernet) + OTA are initialized, so that you can upload a new binary. You can trigger entering safe mode by either configuring a dedicated button or switch to do that or by pressing the reset button on the board for num_attempts times.

# Example configuration entry
ota:
  safe_mode: true
  password: !secret ota_password

Configuration variables:

  • safe_mode (Optional, boolean): Whether to enable safe mode. Defaults to true.

  • 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

  • id (Optional, ID): Manually specify the ID used for code generation.

  • reboot_timeout (Optional, Time): The amount of time to wait before rebooting when in safe mode. Defaults to 5min.

  • num_attempts (Optional, int): The number of attempts to wait before entering safe mode. Defaults to 10.

  • on_begin (Optional, Automation): An action to be performed when an OTA update is started. See on_begin.

  • on_progress (Optional, Automation): An action to be performed (multiple times) during an OTA update. See on_progress.

  • on_end (Optional, Automation): An action to be performed after a successful OTA update. See on_end.

  • on_error (Optional, Automation): An action to be performed after a failed OTA update. See on_error.

  • on_state_change (Optional, Automation): An action to be performed when an OTA update state change happens. See on_state_change.

Note

Please be aware that ESP8266 modules must be reset after a serial upload before OTA can work. When you are trying to conduct an OTA update and receive an error message Bad Answer: ERR: ERROR[11]: Invalid bootstrapping the reason is very likely that power-cycling the ESP module is required once after the serial upload.

OTA Automation

The OTA component provides various automations that can be used to provide feedback during an OTA update. There are a few things to consider when making use of the provided automation triggers:

  • An OTA update blocks the main loop during its operation. This means that you won’t be able to represent state changes using components that update their output only from within their loop() method. Explained differently: if you try to display the OTA progress using component X, but the update only appears after the OTA update finished, then component X cannot be used for providing OTA update feedback.

  • Make sure that your automation actions do not take too much time, to prevent them from blocking the OTA update code for too long.

on_begin

This automation will be triggered when an OTA update is started.

ota:
  on_begin:
    then:
      - logger.log: "OTA start"

on_progress

Using this automation, it is possible to report on the OTA update progress. It will be triggered multiple times during the OTA update. You can get the actual progress percentage (a value between 0 and 100) from the trigger with variable x.

ota:
  on_progress:
    then:
      - logger.log:
          format: "OTA progress %0.1f%%"
          args: ["x"]

on_end

This automation will be triggered when an OTA update has completed successfully, right before the device is rebooted.

Because the update has completed, you can safely use an automation action that takes some time to complete. This can for example be useful if you want to flash a LED or so, in which case a pause would be required to make the LED light up for long enough, before the reboot turns it off.

ota:
  on_end:
    then:
      - logger.log: "OTA end"

on_error

This automation will be triggered when an OTA update has failed. You can get the internal error code with variable x.

Just like for on_end, you can safely use an automation that takes some time to complete, because the OTA update is no longer busy.

ota:
  on_error:
    then:
      - logger.log:
          format: "OTA update error %d"
          args: ["x"]

on_state_change

This automation will be triggered on every state change. You can get the actual state with variable state, which will contain one of values for the OTAState enum. These values are:

  • ota::OTA_STARTED

  • ota::OTA_IN_PROGRESS (will be called multiple times during the update)

  • ota::OTA_COMPLETED

  • ota::OTA_ERROR

ota:
  on_state_change:
    then:
      - if:
          condition:
            lambda: return state == ota::OTA_STARTED
          then:
            - logger.log: "OTA start"

Updating the password:

Changing an existing password:

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

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

Adding a password:

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

See Also