Over-the-Air Updates¶
ESPHome supports remotely updating a device “over-the-air” (OTA). Each update mechanism is a platform of the base
ota
component and will have its own configuration variables.
In release 2024.6.0, the ota
component transistioned from a standalone component to a platform component. This
change was made to facilitate the use of multiple update mechanisms, enabling greater flexibility.
# Example configuration entry
ota:
- platform: ...
Platforms¶
Configuration variables:¶
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 (approximately each second) while an OTA update is in progress. 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.
OTA Automations¶
The OTA component provides various automations that can be used to provide feedback during the OTA update process. When using these automation triggers, note that:
OTA updates block the main application loop while in progress. 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.Your automation action(s) must not consume any significant amount of time; if they do, OTA updates may fail.
on_begin
¶
This automation will be triggered when an OTA update is started.
ota:
- platform: ...
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 repeatedly during the
OTA update. You can get the actual progress percentage (a value between 0 and 100) from the trigger with variable x
.
ota:
- platform: ...
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, immediately before the device is rebooted.
Because the update has completed, you can safely use (an) automation action(s) that takes some time to complete. If, for example, you want to flash an LED, multiple pauses/delays would be required to make the LED blink a few times, before the reboot. The OTA update can’t fail at this point because it is already complete.
ota:
- platform: ...
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 as the OTA update process has already finished.
ota:
- platform: ...
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 repeatedly during the update)ota::OTA_COMPLETED
ota::OTA_ERROR
ota:
- platform: ...
on_state_change:
then:
- if:
condition:
lambda: return state == ota::OTA_STARTED;
then:
- logger.log: "OTA start"
Safe Mode¶
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 the ota
component, but it may be disabled if desired. See
Safe Mode for details.