OTA - xoseperez/espurna GitHub Wiki

Over-the-air updates

ESPurna offers several ways to upgrade an ESPurna device over-the-air:

IMPORTANT NOTICE

When updating from 1.14.1 make sure there is enough available space on the device (usually, "available space" rounded to the nearest 4096 byte increment) to perform the OTA upgrade. Telnet and direct HTTP upgrades with an .bin too big could result in a bricked device. espota.py and Web Interface upgrades will issue a warning.

Make sure to only perform OTA upgrade with a properly powered device. Attempting to flash and / or use a normally AC powered device (like a Sonoff) instead powered through 3v3 may result in unexpected issues with the firmware.

Compressed OTA

Commonly used instead of Two-Step updates

Starting with ESPurna version 1.14.1 and when building with Arduino Core 2.7.4+, it is possible to upload .bin file compressed with gzip

For example, when building with PlatformIO CLI

# will automatically build firmware.bin as a dependency of firmware.bin.gz
$ pio run -e nodemcu-lolin -t .pio/build/nodemcu-lolin/firmware.bin.gz

Otherwise, to manually compress firmware .bin

  • on all platforms, 7-zip with the maximum compression ratio setting.
  • on Linux or macOS, use gzip -9 ...

(notice that 7-zip will generally provide the best compression)

OTA methods

Web interface updates

You can directly upload the firmware file (.bin extension) to the device using the "Upgrade" option in the "Admin" tab of the web interface. You can find the latest firmware images for your device in the releases page.

Updating via HTTP

You can use the "/upgrade" endpoint to automate upgrades via HTTP using cURL or similar tools. This is the same endpoint that uses the web interface upgrade utility so you will need a device with ESPurna compiled with WEB_SUPPORT (this is the default).

$ curl -XPOST --digest -uadmin:<password> \
  -H "Content-Type: multipart/form-data" \
  -F "filename=@<path_to_binary>" \
  http://<ip_device>/upgrade

You will have to replace <password>, <path_to_binary> and <ip_device> with proper values for your device. For instance:

$ curl -XPOST --digest -uadmin:fibonacci \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]/build/esp8266-1m-base/firmware.bin" \
  http://192.168.4.1/upgrade

Please note the '@' before the path to the binary file. The path can be relative to the current directory. The backslashes in a bash console mean that the command continues in the next line, you can write the full curl command in a single line if you want.

Thanks to FlorianSW for this tip, check the #745 for the original suggestion.

Using espota.py

If platformio was used at least once to build and upload ESPurna, espota.py can be found inside .platformio packages directory

~/.platformio/packages/tool-espotapy/espota.py

It can also be found inside of Arduino framework directory

~/.platformio/packages/framework-arduinoespressif8266/tools/espota.py

or latest OTA script version can be fetched directly.

It does require existing firmware .bin file. Example using file from Releases:

$ python espota.py --progress --ip 192.168.4.1 --auth fibonacci --file firmware.bin

Updating from the Terminal

Since version 1.12.4, ESPurna includes an 'ota' command in the terminal that allows you to update the firmware in the device passing the URL of a binary as an argument. The URL can be in the local network or the internet, but the device has to have direct access to that resource (no redirects). HTTPS is only available in a custom build using SECURE_CLIENT.

Simply open a telnet session to the device and request an OTA update passing the URL:

$ telnet 192.168.1.15
ota http://192.168.1.11/espurna-1.12.4a-wemos-d1mini-relayshield.bin
[038771] +OK
[038771] [OTA] Downloading from 'http://192.168.1.11/espurna-1.12.4a-wemos-d1mini-relayshield.bin'
[053298] [OTA] Done, restarting...

Using PlatformIO

platformio.ini file defines following environments for custom builds, including support for OTA updates:

  • esp8266-1m-base
  • esp8266-2m-base
  • esp8266-4m-base

To build with the most recent PlatformIO release:

  • esp8266-{1,2,4}m-latest-base

Also, to build with the current ESP8266 Arduino Core git master version:

  • esp8266-{1,2,4}m-git-base

PlatformIO OTA updates are using special upload build target. Configuration happens either through the usual means, by editing platformio.ini or supplying command line flags to the pio tool. espota.py is used internally to perform network discovery and upload to the device, ESPurna must be built with OTA_ARDUINOOTA_SUPPORT=1. --file=<FIRMWARE BIN> is provided automatically.

Possible environment configuration

[env:myenv]
extends = env:esp8266-1m-git-base
build_src_flags = -DITEAD_SONOFF_BASIC -DDHT_SUPPORT=1
upload_protocol = espota
upload_flags =
  --ip=<DEVICE HOSTNAME OR IP>
  --auth=<DEVICE PASSWORD>

Build and upload

> pio run -e myenv -t upload

(or, by selecting it in the IDE)

Use env to run pio with upload environment variables

> env PLATFORMIO_UPLOAD_PORT=<IP ADDRESS> PLATFORMIO_UPLOAD_ARGS="--auth=<DEVICE PASSWORD> --ip=<DEVICE IP>" PLATFORMIO_BUILD_SRC_FLAGS="-DITEAD_SONOFF_BASIC" pio run -t esp8266-1m-base -t upload

For more information, see espressif8266 platform documentation

Or, alternatively, using our custom environment configuration variables

> env ESPURNA_IP=192.168.1.11 ESPURNA_AUTH=somepassword ESPURNA_FLAGS="-DITEAD_SONOFF_BASIC -DDHT_SUPPORT=1" pio run -e esp8266-1m-base -t upload

(support of these these may be removed in the future)

Or, export environment variables so that they are available for the current session

> export ESPURNA_IP=192.168.1.11
> export ESPURNA_AUTH=somepassword
> export ESPURNA_FLAGS="-DITEAD_SONOFF_BASIC -DDHT_SUPPORT=1"
> pio run -t upload -e esp8266-1m-base

Properly quoting command line

NOTICE that environment variables like $PLATFORMIO_UPLOAD_FLAGS or $ESPURNA_AUTH will be expanded by shell, unless it is properly quoted. See https://github.com/xoseperez/espurna/issues/1498

export ESPURNA_AUTH='123456x$@' # incorrect
export ESPURNA_AUTH=\''password$@'\' # correct

See code/espurna/config/hardware.h for all of the possible -D<BOARD> values.

Backwards compatibility

Before version 1.15.0, these were exclusively OTA environments:

  • esp8266-1m-ota
  • esp8266-2m-ota
  • esp8266-4m-ota

-ota suffix remains for backwards compatibility, but it should not be used when running current version. Environments will be removed in the future, please do not use them to build the firmware.

Troubleshooting

Sometimes OTA updates fail. It happens. It's not a problem since the firmware does not get overwritten if the upload fails. But if you cannot update the device firmware even after several attempts, you might try to check if you have a firewall and disable it.

Automatic OTA updates

You can also use the automatic OTA update feature. Check the NoFUSS library for more info.

This options is disabled by default. Enable it in your firmware setting NOFUSS_SUPPORT=1 in code/espurna/config/general.h or via additional build flag (-DNOFUSS_SUPPORT=1)

Support

If you're looking for support:

  • Issues: this is the most dynamic channel at the moment, you might find an answer to your question by searching open or closed issues.
  • Wiki pages: might not be as up-to-date as we all would like (hey, you can also contribute in the documentation!).
  • Gitter channel: you have better chances to get fast answers from project contributors or other ESPurna users. (also available with any Matrix client!)
  • Issue a question: as a last resort, you can open new question issue on GitHub. Just remember: the more info you provide the more chances you'll have to get an accurate answer.
⚠️ **GitHub.com Fallback** ⚠️