Re-write the 'upgrading firmware' section in the flash docs (#1414)

docs/en/flash.md

@@ -4,7 +4,7 @@ Adafruit provides a really nice [firmware flashing tutorial](https://learn.adafr
 
     Keep in mind that the ESP8266 needs to be [put into flash mode](#putting-device-into-flash-mode) before you can flash a new firmware!
 
-## esptool
+## esptool.py
 > A cute Python utility to communicate with the ROM bootloader in Espressif ESP8266. It is intended to be a simple, platform independent, open source replacement for XTCOM.
 
 Source: [https://github.com/themadinventor/esptool](https://github.com/themadinventor/esptool)
@@ -15,7 +15,7 @@ Supported platforms: OS X, Linux, Windows, anything that runs Python
 
 Run the following command to flash an *aggregated* binary as is produced for example by the [cloud build service](build.md#cloud-build-service) or the [Docker image](build.md#docker-image).
 
-`esptool.py --port <USB-port-with-ESP8266> write_flash -fm <mode> -fs <size> 0x00000 <nodemcu-firmware>.bin`
+`esptool.py --port <serial-port-of-ESP8266> write_flash -fm <mode> -fs <size> 0x00000 <nodemcu-firmware>.bin`
 
 - `mode` is `qio` for 512&nbsp;kByte modules and `dio` for 4&nbsp;MByte modules (`qio` might work as well, YMMV).
 - `size` is given in bits. Specify `4m` for 512&nbsp;kByte and `32m` for 4&nbsp;MByte.
@@ -48,24 +48,32 @@ Otherwise, if you built your own firmware from source code:
 
 Also, in some special circumstances, you may need to flash `blank.bin` or `esp_init_data_default.bin` to various addresses on the flash (depending on flash size and type), see [below](#upgrading-from-sdk-09x-firmware).
 
-If upgrading from [SPIFFS](https://github.com/pellepl/spiffs) version 0.3.2 to 0.3.3 or later, or after flashing any new firmware (particularly one with a much different size), you may need to run [`file.format()`](modules/file.md#fileformat) to re-format your flash filesystem. You will know if you need to do this if your flash files disappeared, or if they exist but seem empty, or if data cannot be written to new files.
+## Upgrading Firmware
-
-## Upgrading from SDK 0.9.x Firmware
 
 !!! important
 
     It goes without saying that you shouldn't expect your NodeMCU 0.9.x Lua scripts to work error-free on a more recent firmware. Most notably Espressif changed the `socket:send` operation to be asynchronous i.e. non-blocking. See [API documentation](modules/net.md#netsocketsend) for details.
 
-If you flash a recent NodeMCU firmware for the first time, it's advisable that you get all accompanying files right. A typical case that often fails is when a module is upgraded from a 0.9.x firmware to the latest version built from the [NodeMCU build service](http://nodemcu-build.com). It might look like the brand new firmware is broken, but the reason for the missing Lua prompt is related to the big jump in SDK versions: Espressif changes the `esp_init_data_default.bin` for their devices along the way with the SDK. So things break when a NodeMCU firmware with a certain SDK is flashed to a module which contains init data from a previous SDK.
+Espressif changes the init data block (`esp_init_data_default.bin`) for their devices along the way with the SDK. So things break when a NodeMCU firmware with a certain SDK is flashed to a module which contains init data from a different SDK. Hence, this section applies to upgrading NodeMCU firmware just as well as *downgrading* firmware.
 
-Download SDK patch 1.5.4.1 (http://bbs.espressif.com/download/file.php?id=1572) and extract `esp_init_data_default.bin` from there. *Use this file together with the new firmware during flashing*. This SDK release introduced an additional sector for RF calibration data. Espressif recommends to clear this one as well in the [release notes](http://bbs.espressif.com/viewtopic.php?f=46&t=2376). The simplest way to set up the flash from scratch is to erase the complete flash before upgrading (or downgrading) SDK versions.
+A typical case that often fails is when a module is upgraded from a 0.9.x firmware to a recent version. It might look like the new firmware is broken, but the reason for the missing Lua prompt is related to the big jump in SDK versions.
 
-**esptool**
+If there is no init data block found during SDK startup, the SDK will install one itself. If there is a previous (potentially too old init block), the SDK *probably* doesn't do anything with it but there is no documentation from Espressif on this topic.
+
+Hence, there are two strategies to update the SDK init data:
+
+- Erase flash completely. This will also erase the (Lua) files you uploaded to the device! The SDK will install the init data block during startup.
+- Don't erase the flash but replace just the init data with a new file during the flashing procedure. For this you would download [SDK patch 1.5.4.1](http://bbs.espressif.com/download/file.php?id=1572) and extract `esp_init_data_default.bin` from there.
+
+When flashing a new firmware (particularly with a much different size), the flash filesystem may be reformatted as the firmware starts. If it is not automatically reformatted, then it should be valid and have the same contents as before the flash operation. You can still run [`file.format()`](modules/file.md#fileformat) to re-format your flash filesystem. You will know if you need to do this if your flash files exist but seem empty, or if data cannot be written to new files. However, this should be an exceptional case.
+
+**esptool.py**
+
+For [esptool.py](https://github.com/themadinventor/esptool) you specify the init data file as an additional file for the `write_flash` command.
 
-For [esptool](https://github.com/themadinventor/esptool) you specify another file to download at the command line.
 ```
-esptool.py erase_flash
+esptool.py --port <serial-port-of-ESP8266> erase_flash
-esptool.py write_flash <flash options> 0x00000 <nodemcu-firmware>.bin 0x7c000 esp_init_data_default.bin
+esptool.py --port <serial-port-of-ESP8266> write_flash <flash options> 0x00000 <nodemcu-firmware>.bin <init-data-address> esp_init_data_default.bin
 ```
 
 !!! note "Note:"