Commit fe22d57

MicroPython is distributed as several firmware variants to suit the amount of

flash on your board:

* The standard build (``ESP8266_GENERIC``) targets boards with **2MiB or more**

of flash. This is the recommended build and the best choice for most users.

* The ``FLASH_1M`` variant is for boards with **1MiB** of flash. It removes

asyncio and FAT-filesystem support, as well as some modules from

micropython-lib.

* The ``FLASH_2M_ROMFS`` variant targets **2MiB** boards and reserves part of

the flash for a read-only ROMFS filesystem.

* The ``FLASH_512K`` variant is for boards with only **512kiB** of flash. It is

highly limited compared to the other builds: there is no filesystem support,

and so features that depend on it won't work (WebREPL, mip, etc.). It also

drops framebuffer support, some Python language features, and has less

detailed error messages. This variant is mainly of interest to users who

build from source and fine-tune parameters for their particular application.

The minimum recommended flash size is therefore 1MiB, with 2MiB or more giving

the best experience.

`ESP8266 download page <https://micropython.org/download/ESP8266_GENERIC/>`_.

The download page offers the firmware variants described above. Pick the one

that matches your board's flash size:

Firmware file Board flash size

``ESP8266_GENERIC-<date>-<version>.bin`` 2MiB-4MiB, 8MiB-16MiB** (the standard build)

``ESP8266_GENERIC-FLASH_1M-<date>-<version>.bin`` 1MiB

``ESP8266_GENERIC-FLASH_2M_ROMFS-<date>-<version>.bin`` 2MiB-4MiB, 8MiB-16MiB** (includes a ROMFS)

``ESP8266_GENERIC-FLASH_512K-<date>-<version>.bin`` 512kiB

** Boards with 8MiB or 16MiB of flash can use the standard build,

but require an manual step to set up the RF calibration data, see :ref:`esp8266_large_flash` below.

For each variant the page lists *release* builds and *preview* builds. If you

are just starting with MicroPython, choose the latest release build. If you are

an experienced user who would like to follow development closely and help with

testing new features, the preview builds are automatic builds of the

development branch.

Throughout the rest of this tutorial the example commands use the standard

``ESP8266_GENERIC`` firmware; substitute the exact filename you downloaded.

The ``--flash_size=detect`` option tells esptool.py to read the flash size from

the chip's JEDEC ID. MicroPython itself also autodetects the flash size at

runtime for chips up to **4MB**, so a single firmware build adapts to the actual

flash on your board without any extra configuration. The filesystem is

automatically sized to use all of the available flash.

The ESP8266 needs a small block of RF calibration data, known as

``esp_init_data``, near the end of the flash before WiFi will start. On first

boot MicroPython checks this region and, if it is blank (for example because you

just ran ``erase_flash``), it automatically writes the default calibration data

for you. For boards with **4MB of flash or less**, no manual step is needed. See

:ref:`esp8266_large_flash` below for boards larger than 4MB.

.. _esp8266_large_flash:

Boards with more than 4MB of flash

Boards with **8MB or 16MB** of flash need one extra step. The flash routines

built into the ESP8266 boot ROM (which MicroPython uses to write the calibration

data on first boot) cannot address flash beyond 4MB: the ROM reads the chip's

device ID but clamps the reported size to 4MB, so any access above that offset

fails. As a result MicroPython can only write the ``esp_init_data`` RF

calibration block automatically within the first 4MB of flash.

So after a full flash erase MicroPython cannot place the calibration data at the correct end-of-flash

address by itself. Without it the WiFi subsystem will not start (typically

showing up as a continuous reset loop or ``rf_cal`` errors). For more background

on this ROM limitation see

`ESP8266 16MB Flash Handling <https://piers.rocks/esp8266/16mb/flash/eeprom/2016/10/14/esp8266-16mbyte-flash_handling.html>`_.

To fix this, flash the ``esp_init_data_default.bin`` file (shipped with the

Espressif NONOS SDK) to the calibration address, which is the flash size minus

``0x4000``, see table below.

You can download ``esp_init_data_default.bin`` from the Espressif repository

(open the link and click "View raw" to download the file):

`<https://github.com/espressif/ESP8266_AT/blob/master/bin/esp_init_data_default.bin>`__

The calibration addresses are:

Flash size ``esp_init_data`` address

8MB ``0x7FC000``

16MB ``0xFFC000``

The full procedure for a 16MB board is::

For an 8MB board, use ``0x7FC000`` in step 3 and ``--flash_size 8MB`` in step 4.

The filesystem is sized automatically from the detected flash size, so it

will use all of the available space once the board boots.

* If lower baud rate didn't help, you may want to try a different version of

esptool.py, which may use a different programming algorithm.