Documentation suggestion: write_flash sometimes needs argument 0x00 instead of 0x1000

[donburch888]

In the "1.4 deploying the firmware" section on "Getting started with MicroPython on the ESP32" page the write_flash command uses an argument of "0x1000".
Following this command I tried several versions of the ESP32-S3 firmware, each time resulting in a continual "invalid header 0x0FFFFFFF" message when I rebooted after connecting minicom serial.
It took some time before I discovered a post (I don't remember where) which suggested to try 0x0 - which worked for me.

I suggest adding to the Troubleshooting section a little further down that page:

• The flashing instructions above load the file into memory starting at memory location 0x1000, which is common for some of the earlier ESP32 chips with less memory. You can also try using 0x0 instead of 0x1000.

[ekspla]

If you had downloaded the firmware from the official download site, you could have seen the correct instrucion as follows:

esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash -z 0 board-20210902-v1.17.bin

[donburch888]

I did download from that page, and it does have the correct write_flash address ... yes.

But I was following the official website instructions for deploying the firmware - which I am supposed to have known is incorrect ? Saying "you should have known" is nowhere as helpful to newbies as providing the correct information in one place where users can find it.

So I come back to suggesting an amendment to the Getting started with MicroPython on the ESP32 page. As well as my first suggestion, maybe also change from
"And then deploy the new firmware using:"
to
"And then deploy the new firmware as per the Installation Instructions on the download page, similar to:"

[scruss]

The amendment is a good idea, but note that the guide is Getting started with MicroPython on the ESP32, and not … on the ESP32-S3. The ESP32 have a whole mix of peripherals, so writing one guide for all of them would be confusing

[ekspla]

OP might have thought ESP32-S3 as a kind of ESP32's variant.
ESP32 and ESP32-S3 (and also ESP32-C*) are different processors, though they have confusing names.

[projectgus]

The amendment is a good idea, but note that the guide is Getting started with MicroPython on the ESP32, and not … on the ESP32-S3. The ESP32 have a whole mix of peripherals, so writing one guide for all of them would be confusing

The sticking point is that MicroPython only has docs for the "esp32" port, which includes all the ESP32 family chips. It's currently extra confusing because many docs pages (like this one) haven't been completely updated as new ESP32 family chips have been supported.

This is slowly changing, for example the TouchPad docs got updated to mention newer chips in #16169 . It's a lot of work, though - more PRs welcome!

[projectgus]

Thanks very much for pointing this out, @donburch888. This docs page dates from the "original" ESP32 chip and haven't been updated for the newer chips in the ESP32 family which have a different flash address.

I had a "todo" list item to clean up some of the esp32 flashing steps in other ways, and I've incorporated a fix for this in that work: #16535