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:¶
All automations supported by Over-the-Air Updates.
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 withmd5_url
(below); must be specified ifmd5_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 withmd5
(above); must be specified ifmd5
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
andpassword
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 thefirmware.md5
file. Themd5_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.