From c3a66e42c07268acaeec5d085163dfb4d15545c6 Mon Sep 17 00:00:00 2001 From: Michael Ingraham <34340210+meingraham@users.noreply.github.com> Date: Fri, 4 Oct 2019 09:56:16 -0400 Subject: [PATCH] Updated Upgrade (markdown) --- Upgrade.md | 65 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/Upgrade.md b/Upgrade.md index 328618ac..f16dd63e 100644 --- a/Upgrade.md +++ b/Upgrade.md @@ -1,9 +1,11 @@ -For first-time flashers, please follow the [Upload instructions](Flashing) to initially flash the Sonoff-Tasmota firmware onto your Sonoff module. +For first-time flashers, please follow the [Upload instructions](Flashing) to initially flash Tasmota firmware onto your device. + +The first rule of upgrading: _**If it ain't broke, don't fix it!**_ In other words, ensure that there is a good reason to mess with a working installation (e.g., a need to use a new feature or address a found problem fixed in a more current version). + +Any time you upgrade it is highly recommended that you [back up your device settings](#device-settings). This is found in the web UI under the `Configuration` menu. ## Upgrading via OTA - -It is recommended (and more convenient) to upgrade the firmware of a Sonoff module [over-the-air](https://en.wikipedia.org/wiki/Over-the-air_programming), without a serial connection, while being connected to AC and operational. -This method is only available after the Sonoff-Tasmota firmware was flashed via serial connection once. +It is recommended (and more convenient) to upgrade the device firmware [over-the-air](https://en.wikipedia.org/wiki/Over-the-air_programming), without a serial connection, while being connected to AC and operational. ### OTA Upgrade Methods @@ -11,28 +13,26 @@ This method is only available after the Sonoff-Tasmota firmware was flashed via There are a few ways to upgrade the firmware: -1. Use the "Upgrade by file upload" dialog on the Sonoff-Tasmota web interface to flash an available firmware binary file (e.g. `firmware.bin`) -2. Use the "Upgrade by web server" dialog on the Sonoff-Tasmota web interface to flash a firmware binary file provided on a web server -3. Initiate the upgrade via the serial/MQTT/web command [`upgrade`](https://github.com/arendst/Sonoff-Tasmota/wiki/Commands#management) +1. Use the "Upgrade by file upload" dialog on the Tasmota web interface to flash an available firmware binary file (e.g. `firmware.bin`) +2. Use the "Upgrade by web server" dialog on the Tasmota web interface to flash a firmware binary file provided on a web server +3. Initiate the upgrade via the serial/MQTT/web command [`upgrade`](Commands#management) -*Bonus for openHAB users:* Implement an [automation rule](https://github.com/arendst/Sonoff-Tasmota/wiki/openHAB#maintenance-actions) to upgrade your Sonoffs from within openHAB. +*Bonus for openHAB users:* Implement an [automation rule](openHAB#maintenance-actions) to upgrade your devices from within openHAB. ### Firmware Binary Sources Build the firmware binary from source or download the latest build. -The latest build can be found in the [GitHub releases section](https://github.com/arendst/Sonoff-Tasmota/releases). -A secondary host for OTA upgrades is provided on [thehackbox](http://thehackbox.org/tasmota/release/) because GitHub will only serve files over HTTPS, which is not supported by the Sonoff-Tasmota firmware. +The latest build can be found in the [GitHub releases section](releases). +A secondary host for OTA upgrades is provided on [thehackbox](http://thehackbox.org/tasmota/release/) because GitHub will only serve files over HTTPS, which is not supported by the Tasmota firmware. -A full list of available builds for the latest release can be found in [the releases section](https://github.com/arendst/Sonoff-Tasmota/releases). - -**Bonus - Update Notification:** [@smadds](https://github.com/arendst/Sonoff-Tasmota/issues/19) also publishes the latest released version number to a publicly available MQTT server which may be subscribed to at `sonoff.maddox.co.uk:1883` with the topic `sonoff-version`. No authentication needed. +A full list of available builds for the latest release can be found in [the releases section](releases). ### Functionality vs Firmware size vs OTA -As more functionality is being added to the firmware at some time it reaches the point where OTA or web page upload will fail. Both upgrade features rely on the fact that there is enough free flash memory available to load both the current and the new firmware. With a 1MB flash as available on the Sonoffs and the standard linker script providing 950kB code space a firmware file size of as much as 475kB allows for an easy upgrade. +As more functionality is being added to the firmware at some time it reaches the point where OTA or web page upload will fail. Both upgrade features rely on the fact that there is enough free flash memory available to load both the current and the new firmware. With a 1MB flash as available on most ESP82xx devices and the standard linker script providing 950kB code space a firmware file size of as much as 475kB allows for an easy upgrade. -Starting with **version 5.x** Sonoff-Tasmota uses an updated linker script, extending the code space by 70kB, allowing a firmware file size of as much as 510kB. +Starting with **version 5.x** Tasmota uses an updated linker script, extending the code space by 70kB, allowing a firmware file size of as much as 510kB. Larger firmware files can only be loaded when the current flash usage is first reduced to accommodate more free flash to load the new firmware. Hence you'll need to perform a two step process: 1. Upload firmware with `#define FIRMWARE_MINIMAL` **enabled** (remove the slashes) which will have a smaller footprint @@ -41,22 +41,39 @@ Larger firmware files can only be loaded when the current flash usage is first r This applies if you are not building your own firmware, too - use the `-minimal` firmware image first, then load the normal one. ## Migration path - -Until now several versions of my Sonoff software have been released starting with the C version Sonoff-MQTT-OTA followed by Sonoff-MQTT-OTA-Arduino and Sonoff-Tasmota. +Until now several versions of Tasmota have been released starting with the C version Sonoff-MQTT-OTA followed by Sonoff-MQTT-OTA-Arduino and Sonoff-Tasmota. Migrating from one version to the next versions is mostly painless as the settings are saved in the same location in flash and newer settings are appended. As said, mostly painless. There are some deviations to this rule as I rearranged the flash. In the next list you'll find an overview of supported migrations paths. -1. No migration from **Sonoff-MQTT-OTA** to **Sonoff-MQTT-OTA-Arduino** or **Sonoff-Tasmota**.
The settings flash lay-out and OTA image locations are different from the Arduino versions -2. Easy migration from **Sonoff-MQTT-OTA-Arduino 1.0.11** to **Sonoff-Tasmota 3.9.x**.
After installing Sonoff-Tasmota for the first time some settings need to be adjusted via web configuration or MQTT commands. -3. Easy migration from **Sonoff-MQTT-OTA-Arduino 3.1.0** to **Sonoff-Tasmota 4.x**.
After installing Sonoff-Tasmota for the first time some settings need to be adjusted via web configuration or MQTT commands. -4. Easy migration from **Sonoff-Tasmota 4.x** to **Sonoff-Tasmota 5.14**.
As a safeguard perform a Backup Configuration before installing the new version. If settings are lost after the upgrade perform a Restore Configuration. -5. Easy migration from **Sonoff-Tasmota 5.2** to **Sonoff-Tasmota 6.x**.
As a safeguard perform a Backup Configuration before installing the new version. If settings are lost after the upgrade perform a Restore Configuration. +* No migration from **Sonoff-MQTT-OTA** to **Sonoff-MQTT-OTA-Arduino** or **Sonoff-Tasmota**. + The settings flash lay-out and OTA image locations are different from the Arduino versions +* Easy migration from **Sonoff-MQTT-OTA-Arduino 1.0.11** to **Sonoff-Tasmota 3.9.x**. + After installing Sonoff-Tasmota for the first time some settings need to be adjusted via web configuration or MQTT commands. +* Easy migration from **Sonoff-MQTT-OTA-Arduino 3.1.0** to **Sonoff-Tasmota 4.x**. + After installing Sonoff-Tasmota for the first time some settings need to be adjusted via web configuration or MQTT commands. +* Easy migration from **Sonoff-Tasmota 4.x** to **Sonoff-Tasmota 5.14**. + As a safeguard perform a Backup Configuration before installing the new version. If settings are lost after the upgrade perform a Restore Configuration. +* Easy migration from **Sonoff-Tasmota 5.2** to **Tasmota 6.x**. + As a safeguard perform a Backup Configuration before installing the new version. If settings are lost after the upgrade perform a Restore Configuration. -So to migrate from **Sonoff-MQTT-OTA-Arduino versions before 3.1.0** to **Sonoff-Tasmota 6.x** you will need to take four steps: +So to migrate from **Sonoff-MQTT-OTA-Arduino versions before 3.1.0** to **Tasmota 6.x** you will need to take four steps: 1. Migrate to **Sonoff-Tasmota 3.9.x** 2. Migrate to **Sonoff-Tasmota 4.x** 3. Migrate to **Sonoff-Tasmota 5.14** -4. Migrate to **Sonoff-Tasmota 6.x** +4. Migrate to **Tasmota 6.x** + +# Device Settings +Tasmota uses flash memory to store many options and settings. Newer versions of Tasmota add features and use more and more of this area than earlier versions. These regions of flash were therefore not used by Tasmota before. If you did not erase flash when you originally flashed your device, a newer update may be accessing areas with values left over from the original factory firmware. Therefore there could be unexpected behavior. It is best to address this before upgrading across major versions of Tasmota. + +1. Make a configuration backup using one of these two methods: + - Use `decode-config.py` from the Tasmota [`tools` code folder](../tree/development/tools) to create the backup in human readable form: + `decode-config.py -d --backup-file Config-@H-@f-@v --backup-type json` + - If you have a `.dmp` backup already, you can create a JSON extract from that file: + `decode-config.py -f --backup-file Config-@H-@f-@v --backup-type json` +2. Perform a `Reset 6` (erases flash settings area but retains Wi-Fi and MQTT settings) +3. Upgrade the firmware +4. Restore configuration + Particularly the older your current Tasmota versions is, it is probably best not to restore the backup directly since there may be some outdated settings in your configuration. There are often newer better alternatives, particularly since an upgrade is normally done to use new features. Configure the device manually referring to the [Commands article](Commands) and the settings (e.g., SetOptions, Rules, etc.) in the JSON file you created in step #1.