OTA Update via HTTP Request

The OTA (Over The Air) via HTTP Request update component allows your devices to install updated firmware on their own. To use it, in your device’s configuration, you specify a URL from which the device will download the binary file (firmware). To trigger the update, an ESPHome action is used which initiates the download and installation of the new firmware. Once complete, the device is rebooted, invoking the new firmware.

Since the device functions as an HTTP(S) client, it can be on a foreign network or behind a firewall. This mechanism is primarily useful with either standalone or MQTT-only devices.

To use this platform, the OTA Update via HTTP Request component must be present in your configuration.

# Example configuration entry
ota:
  - platform: http_request

Configuration variables:

ota.http_request.flash Action

This action triggers the download and installation of the updated firmware from the configured URL. As it’s an ESPHome action, it may be used in any ESPHome automation(s).

on_...:
  then:
    - ota.http_request.flash:
        md5_url: http://example.com/firmware.md5
        url: https://example.com/firmware.ota.bin
    - logger.log: "This message should be not displayed because the device reboots"

Configuration variables:

  • md5 (Optional, string, templatable): The MD5sum of the firmware file pointed to by url (below). May not be used with md5_url (below); must be specified if md5_url is not.

  • md5_url (Optional, string, templatable): The URL of the file containing an MD5sum of the firmware file pointed to by url (below). May not be used with md5 (above); must be specified if md5 is not.

  • url (Required, string, templatable): The URL of the binary file containing the (new) firmware to be installed.

  • username (Optional, string, templatable): The username to use for HTTP basic authentication.

  • password (Optional, string, templatable): The password to use for HTTP basic authentication.

Note

  • You can obtain the firmware.ota.bin file from either:

    • ESPHome dashboard (HA add-on): download in “OTA format” (formerly “legacy format”)

    • ESPHome CLI: the directory .esphome/build/project/.pioenvs/project/firmware.ota.bin

      …where “project” is the name of your ESPHome device/project.

    You cannot use firmware.factory.bin or “Factory format” (formerly “Modern format”) with this component.

  • username and password must be URL-encoded if they include special characters.

  • The MD5sum of the firmware binary file is an ASCII file (also known as “plain text”, typically found in files with a .txt extension) consisting of 32 lowercase hexadecimal characters. It can be obtained and saved to a file with the following command(s):

    • On macOS:

      md5 -q firmware.ota.bin > firmware.md5

    • On most Linux distributions:

      md5sum firmware.ota.bin > firmware.md5

    • On Windows/PowerShell:

      (Get-FileHash -Path firmware.ota.bin -Algorithm md5).Hash.ToLower() | Out-File -FilePath firmware.md5 -Encoding ASCII

    This will generate the MD5 hash of the firmware.ota.bin file and write the resulting hash value to the firmware.md5 file. The md5_url configuration variable should point to this file on the web server. It is used by the OTA updating mechanism to ensure the integrity of the (new) firmware as it is installed.

    If, for any reason, the MD5sum provided does not match the MD5sum computed as the firmware is installed, the device will continue to use the original firmware and the new firmware is discarded.

See Also