Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

ESPHome supports updating device firmware wirelessly without a physical USB connection. As of ESPHome 2024.6.0, OTA functionality is organized as a platform component — each update mechanism is a separate platform under the ota: list key. The most common platform is esphome, which implements the native OTA protocol used by the ESPHome dashboard and CLI. Additional platforms include http_request for pull-based URL updates, web_server for browser-based uploads, and zephyr_mcumgr for nRF52 boards. Safe mode (automatic recovery) is automatically enabled alongside OTA and can be found at the Safe Mode section below.

​
Minimal Example

ota:
  - platform: esphome
    password: !secret ota_password

​
Configuration Variables (All Platforms)

​
on_begin
Automation
Triggered when an OTA update starts. Keep the automation fast — OTA blocks the main loop while in progress and long-running actions will cause the update to fail.
​
on_progress
Automation
Triggered approximately once per second during an update. The variable x (float, 0–100) contains the current percentage. Suitable for driving a progress indicator on a display.
​
on_end
Automation
Triggered when the update has completed successfully, just before the device reboots into the new firmware. At this point the OTA process is finished and longer-running actions are safe.
​
on_error
Automation
Triggered when the update fails. The variable x (int) contains the internal error code.
​
on_state_change
Automation
Triggered on every OTA state transition. The variable state is of type OTAState with values: ota::OTA_STARTED, ota::OTA_IN_PROGRESS, ota::OTA_COMPLETED, ota::OTA_ERROR.

​
Available Platforms

​
esphome Platform (Native OTA)

The default OTA method used by esphome upload, esphome run, and the dashboard. Communicates over the ESPHome native protocol. 
ota:
  - platform: esphome
    password: !secret ota_password
Platform-specific variables:
​
password
string
Password required to authorize firmware uploads. Strongly recommended for all production devices. Leave empty to disable password protection (not recommended).

​
http_request Platform (Pull-Based OTA)

Pulls firmware from a remote HTTP/HTTPS URL. Useful for fleet updates without direct network access to devices. 
ota:
  - platform: http_request
    url: https://firmware.example.com/devices/mydevice/firmware.bin
    verify_ssl: true

​
web_server Platform

Enables firmware upload through the device’s built-in web server UI or via esphome upload --ota-platform web_server. 
ota:
  - platform: web_server

​
Advanced Example with Progress Feedback

ota:
  - platform: esphome
    password: !secret ota_password
    on_begin:
      then:
        - logger.log: "OTA update starting…"
        - light.turn_on:
            id: status_led
            effect: "Fast Blink"

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

    on_end:
      then:
        - logger.log: "OTA complete — rebooting"
        - light.turn_off: status_led

    on_error:
      then:
        - logger.log:
            format: "OTA failed! Error code: %d"
            args: ["x"]
        - light.turn_on:
            id: status_led
            red: 100%
            green: 0%
            blue: 0%

​
State Change Automation

ota:
  - platform: esphome
    on_state_change:
      then:
        - if:
            condition:
              lambda: return state == ota::OTA_STARTED;
            then:
              - logger.log: "OTA started"
        - if:
            condition:
              lambda: return state == ota::OTA_COMPLETED;
            then:
              - logger.log: "OTA completed successfully"

​
Multiple OTA Platforms

ota:
  - platform: esphome
    password: !secret ota_password

  - platform: http_request
    url: https://updates.myserver.com/firmware/living_room.bin

​
Safe Mode

Safe mode is automatically enabled when any OTA platform is configured. It provides a recovery mechanism if a bad firmware update prevents the device from functioning correctly. If the device fails to boot successfully within the configured boot_is_good_after window (default 60 seconds), it reverts to a minimal safe-mode firmware that only exposes OTA, allowing you to push a corrected build. For full safe mode configuration options, see the Safe Mode Guide.
OTA updates block the main application loop while in progress. Components that only update their output from loop() (e.g. some display drivers) cannot be used to show OTA progress. Use components with direct hardware write capabilities (GPIO LEDs, display components with immediate rendering) for progress indicators.
Never leave OTA unprotected on a device accessible from an untrusted network. Always set a strong password on the esphome platform. Consider using signed OTA verification on ESP32 for production deployments.
On ESP32, OTA rollback is enabled by default via esp32.framework.advanced.enable_ota_rollback: true. If the device crashes before safe_mode marks the boot as successful, the bootloader automatically rolls back to the previous working firmware. This requires the bootloader to be compiled with rollback support — serial-flash the first time to ensure the correct bootloader is installed.

Build docs developers (and LLMs) love

Get started for freeTalk to us