-
Notifications
You must be signed in to change notification settings - Fork 637
ESPurna offers several ways to upgrade an ESPurna device over-the-air:
- PlatformIO (using commandline or VSCode extension)
- Using espota.py (for PlatformIO or Arduino IDE)
- Web interface updates (uploading a binary image from the web UI)
- Terminal updates (connecting via serial or telnet and providing a URL of an image)
- HTTP updates (POSTing a binary image to the device)
- Automatic OTA updates (using the NoFUSS library, not supported by default)
platformio.ini file defines following environments for custom builds, including support for OTA updates:
- esp8266-1m-base
- esp8266-1m-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
NOTE: previously named: esp8266-1m-ota, esp8266-2m-ota and esp8266-4m-ota
And example of use is:
$ 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
You can also prepend envirionment variables instead of exporting them:
$ env ESPURNA_IP=192.168.1.11 ESPURNA_AUTH=somepassword ESPURNA_FLAGS="-DITEAD_SONOFF_BASIC -DDHT_SUPPORT=1" pio run -t upload -e esp8266-1m-base
NOTE: $ESPURNA_AUTH will be expanded by shell, unless it is properly quoted. See https://github.com/xoseperez/espurna/issues/1498
export ESPURNA_AUTH='123456x$@'
=>export ESPURNA_AUTH=\''password$@'\'
See code/espurna/config/hardware.h
for possible -D<BOARD>
values.
NOTE: -ota suffix is no longer required, any env: will accept ESPURNA_... environment variables
Once you have flashed your board with the ESPurna firmware you can flash it again over-the-air using PlatformIO and the -ota
environment:
$ pio run -t upload -e itead-sonoff-basic-ota
See code/platformio_ota.ini
for the current list.
When using OTA environment it defaults to the IP address 192.168.4.1
(device IP in SoftAP mode) and fibonacci
as password. If you want to flash it when connected to your home network or use different password, you must set ESPURNA_IP
and ESPRUNA_AUTH
environment variables:
$ export ESPURNA_IP=192.168.1.11
$ export ESPURNA_AUTH=somepassword
$ pio run -t upload -e itead-sonoff-basic-ota
Or, on Windows:
C:\espurna\code> set ESPURNA_IP=192.168.1.11
C:\espurna\code> set ESPURNA_AUTH=somepassword
C:\espurna\code> pio run -t upload -e itead-sonoff-basic-ota
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.
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 is also can be found inside 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 espurna-<version>-itead-sonoff-basic.bin
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.
From 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 not supported at the moment.
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...
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]/esp8266-1m-ota/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.
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
)
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.
- Backup the stock firmware
- Flash a pre-built binary image
- Flash a virgin Itead Sonoff device without opening
- Flash TUYA-based device without opening
- Flash Shelly device without opening
- Using PlatformIO
- from Visual Studio Code
- Using Arduino IDE
- Build the Web Interface
- Over-the-air updates
- Two-step updates
- ESPurna OTA Manager
- NoFUSS
- Troubleshooting
- MQTT
- REST API
- Domoticz
- Home Assistant
- InfluxDB
- Prometheus metrics
- Thingspeak
- Alexa
- Google Home
- Architecture
- 3rd Party Plugins
- Coding style
- Pull Requests