Rework flashing instructions to clarify need for SDK init data

[jimparis]

Addresses stuff raised in #1500.

• This PR is for the dev branch rather than for master.
• This PR is compliant with the other contributing guidelines as well (if not, please describe why).
• I have thoroughly tested my contribution.
• The code changes are reflected in the documentation at docs/en/*.

Since 1.5.4.1, flashing esp_init_data_default.bin is no longer optional, even on a fully erased chip. Update documentation to clarify that it must be flashed anytime it is missing, or whenever the SDK version changes. This restructures the document a bit in the process.

# Testing with and without flashing esp_init_data_default.bin on an ESP-WROOM-02:

git checkout 1.5.1-master_20160603
make clean
make
esptool.py erase_flash
esptool.py write_flash -m qio -fs 32m 0x00000 bin/0x00000.bin 0x10000 bin/0x10000.bin
# Boots NodeMCU 1.5.1 successfully

git checkout 1.5.4.1-master_20161001
make clean
make
esptool.py erase_flash
esptool.py write_flash -m qio -fs 32m 0x00000 bin/0x00000.bin 0x10000 bin/0x10000.bin
# Prints error "rf_cal[0] !=0x05,is 0xFF", fails to boot to NodeMCU

git checkout 1.5.4.1-master_20161001
make clean
make
esptool.py erase_flash
esptool.py write_flash -m qio -fs 32m 0x00000 bin/0x00000.bin 0x10000 bin/0x10000.bin 0x3fc000 ~/sdk-1.5.4.1/bin/esp_init_data_default.bin
# Boots NodeMCU 1.5.4.1 successfully

[drawkula]

What does esptool.py make ... do and which version of esptool.py are you using?

[jimparis]

Sorry, that was just some cut and paste errors that made it into my PR description. Fixed. I don't think any of that made it into the documentation itself (but more eyes are welcome!).

[devsaurus]

You could mention that the location depends on the size setting provided with the -fs option and both have to be consistent. Thus "size of your flash memory" above doesn't refer to the physical size of the chip but to the size given with -fs, as mentioned in https://github.com/themadinventor/esptool#flash-size---flash_size--fs.

[jimparis]

Good point, but the physical size of the chip does matter due to the "Self adjust flash size" in nodemcu_init. On my 4 MB module, here's what happens:

• Erase chip
• Flash as a 2MB module with: esptool.py write_flash -m qio -fs 16m 0x00000 combined.bin 0x1fc000 esp_init_data_default.bin
• At boot, NodeMCU runs, but reports "Self adjust flash size" and reboots
• ESP8266 is now stuck in a loop, printing ""rf_cal[0] !=0x05,is 0xFF"

I think that the "self adjust flash size" step can't work on a 1.5.4.1 firmware unless NodeMCU also moves the SDK data.

[jmattsson]

Agreed. I really want the esp_init_data_default to be completely hidden from the user by default and have NodeMCU just Do The Right Thing automatically. Which, hopefully, we have in 1526. A user laying down custom init data should be optional, it's far too much a hassle otherwise, as @marcelstoer has discovered.

[jmattsson]

Before merging this, could you guys please try out #1526 ? It might avoid having to document this whole rf_cal[0] mess...

[jimparis]

Works for me (details at #1526). I can adjust this documentation to take that into account. I still think it's an overall improvement.

[devsaurus]

Thanks for clarifying this @jimparis. Size spec while flashing vs. auto detection by the firmware - what a mess.
I tend to agree with Johny that users shouldn't have to deal with init data, but this also implies that the smart parts of the firmware have to be reliable and match all module configurations on the market.
For the docs: the user shall neither specify flash size nor init data since FW does the right thing (tm)?

[jimparis]

Superseded by #1527