Skip to content

Latest commit

 

History

History
112 lines (77 loc) · 4.76 KB

http_request.rst

File metadata and controls

112 lines (77 loc) · 4.76 KB
Raw

OTA Update via HTTP Request

.. seo::
    :description: Instructions for setting up Over-The-Air (OTA) updates for ESPs to download firmwares remotely by HTTP.
    :image: system-update.svg

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 :ref:`action <config-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 :doc:`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 :ref:`action <config-action>`, it may be used in any ESPHome :ref:`automation(s) <automation>`.

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:

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