Flash Modes

write_flash and some other commands accept command line arguments to set bootloader flash mode, flash size and flash clock frequency. The chip needs correct mode, frequency and size settings in order to run correctly - although there is some flexibility. A header at the beginning of a bootable image contains these values.

To override these values, the options --flash_mode, --flash_size and/or --flash_freq must appear after write_flash on the command line, for example:

esptool.py --port /dev/ttyUSB1 write_flash --flash_mode dio --flash_size 4MB 0x0 bootloader.bin

These options are only consulted when flashing a bootable image to an ESP32-C61 at offset 0x0. These are addresses used by the ROM bootloader to load from flash. When flashing at all other offsets, these arguments are not used.

Flash Mode (–flash_mode, -fm)

These set Quad Flash I/O or Dual Flash I/O modes. Valid values are keep, qio, qout, dio, dout. The default is keep, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ESPTOOL_FM.

Most ESP32-C61 modules use qio, but are also dual I/O.

In qio mode, two additional GPIOs (9 and 10) are used for SPI flash communications. If flash mode is set to dio then these pins are available for other purposes.

For a full explanation of these modes, see the SPI Flash Modes page.

Flash Frequency (–flash_freq, -ff)

Clock frequency for SPI flash interactions. Valid values are keep, 40m, 20m, 80m (MHz). The default is keep, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ESPTOOL_FF.

The flash chip connected to most chips works with 40MHz clock speeds, but you can try lower values if the device won’t boot. The highest 80MHz flash clock speed will give the best performance, but may cause crashing if the flash or board design is not capable of this speed.

Flash Size (–flash_size, -fs)

Size of the SPI flash, given in megabytes.

Valid values are: keep, detect, 1MB, 2MB, 4MB, 8MB, 16MB

Note

Esptool uses power of two units, so in IEC units the size arguments are Mebibytes, although Espressif’s technical documentation doesn’t use the Mebi- prefix. This is due to compatibility reasons and to keep consistent with flash manufacturers.

The default --flash_size parameter is keep. This means that if no --flash_size argument is passed when flashing a bootloader, the value in the bootloader .bin file header is kept instead of detecting the actual flash size and updating the header.

To enable automatic flash size detection based on SPI flash ID, add the argument esptool.py [...] write_flash [...] -fs detect. If detection fails, a warning is printed and a default value of of 4MB (4 megabytes) is used.

If flash size is not successfully detected, you can find the flash size by using the flash_id command and then looking up the ID from the output (see Read SPI flash id). Alternatively, read off the silkscreen labelling of the flash chip and search for its datasheet.

The default flash_size parameter can also be overridden using the environment variable ESPTOOL_FS.

The ESP-IDF flashes a partition table to the flash at offset 0x8000. All of the partitions in this table must fit inside the configured flash size, otherwise the ESP32-C61 will not work correctly.