1{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000"}
2
3{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"}
4
5{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"}
6
7{IDF_TARGET_FLASH_FREQ:default="``40m``, ``26m``, ``20m``, ``80m``", esp32c2="``30m``, ``20m``, ``15m``, ``60m``", esp32h2="``24m``, ``16m``, ``12m``, ``48m``", esp32c6="``40m``, ``20m``, ``80m``"}
8
9
10.. _flash-modes:
11
12Flash Modes
13===========
14
15``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.
16A header at the beginning of a bootable image contains these values.
17
18To override these values, the options ``--flash_mode``, ``--flash_size`` and/or ``--flash_freq`` must appear after ``write_flash`` on the command line, for example:
19
20::
21
22    esptool.py --port /dev/ttyUSB1 write_flash --flash_mode dio --flash_size 4MB 0x0 bootloader.bin
23
24These options are only consulted when flashing a bootable image to an {IDF_TARGET_NAME} at offset {IDF_TARGET_BOOTLOADER_OFFSET}. These are addresses used by the ROM bootloader to load from flash. When flashing at all other offsets, these arguments are not used.
25
26Flash Mode (--flash_mode, -fm)
27-------------------------------
28
29These 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``.
30
31.. only:: esp8266
32
33    Most boards use ``qio`` mode. Some ESP8266 modules, including the ESP-12E modules on some (not all) NodeMCU boards, are dual I/O and the firmware will only boot when flashed with ``--flash_mode dio``.
34
35.. only:: not esp8266
36
37    Most {IDF_TARGET_NAME} modules use ``qio``, but are also dual I/O.
38
39In ``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.
40
41For a full explanation of these modes, see the :ref:`SPI Flash Modes page <spi-flash-modes>`.
42
43Flash Frequency (--flash_freq, -ff)
44------------------------------------
45
46Clock frequency for SPI flash interactions. Valid values are ``keep``, {IDF_TARGET_FLASH_FREQ} (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``.
47
48The flash chip connected to most chips works with {IDF_TARGET_FLASH_FREQ_0}MHz clock speeds, but you can try lower values if the device won't boot. The highest {IDF_TARGET_FLASH_FREQ_F}MHz flash clock speed will give the best performance, but may cause crashing if the flash or board design is not capable of this speed.
49
50Flash Size (--flash_size, -fs)
51-------------------------------
52
53Size of the SPI flash, given in megabytes.
54
55.. only:: esp8266
56
57    Valid values are: ``keep``, ``detect``, ``256KB``, ``512KB``, ``1MB``, ``2MB``, ``4MB``, ``2MB-c1``, ``4MB-c1``, ``8MB``, ``16MB``
58
59.. only:: esp32 or esp32c3 or esp32c6 or esp32c2 or esp32h2
60
61    Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``
62
63.. only:: esp32s2 or esp32s3 or esp32p4
64
65    Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``, ``32MB``, ``64MB``, ``128MB``
66
67.. note::
68
69    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.
70
71.. only:: esp8266
72
73    For ESP8266, some :ref:`additional sizes & layouts for OTA "firmware slots" are available <esp8266-and-flash-size>`.
74
75The 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.
76
77To 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.
78
79If 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 :ref:`Read SPI flash id <read-spi-flash-id>`).
80Alternatively, read off the silkscreen labelling of the flash chip and search for its datasheet.
81
82The default ``flash_size`` parameter can also be overridden using the environment variable ``ESPTOOL_FS``.
83
84.. only:: esp8266
85
86    The ESP8266 SDK stores WiFi configuration at the "end" of flash, and it finds the end using this size. However there is no downside to specifying a smaller flash size than you really have, as long as you don't need to write an image larger than this size.
87
88    ESP-12, ESP-12E and ESP-12F modules (and boards that use them such as NodeMCU, HUZZAH, etc.) usually have at least 4 megabyte / ``4MB`` (sometimes labelled 32 megabit) flash.
89
90    .. _esp8266-and-flash-size:
91
92    If using OTA, some additional sizes & layouts for OTA "firmware slots" are available. If not using OTA updates then you can ignore these extra sizes:
93
94    +-------------------+-----------------------+-----------------+-----------------+
95    | flash_size arg    | Number of OTA slots   | OTA Slot Size   | Non-OTA Space   |
96    +===================+=======================+=================+=================+
97    | 256KB             | 1 (no OTA)            | 256KB           | N/A             |
98    +-------------------+-----------------------+-----------------+-----------------+
99    | 512KB             | 1 (no OTA)            | 512KB           | N/A             |
100    +-------------------+-----------------------+-----------------+-----------------+
101    | 1MB               | 2                     | 512KB           | 0KB             |
102    +-------------------+-----------------------+-----------------+-----------------+
103    | 2MB               | 2                     | 512KB           | 1024KB          |
104    +-------------------+-----------------------+-----------------+-----------------+
105    | 4MB               | 2                     | 512KB           | 3072KB          |
106    +-------------------+-----------------------+-----------------+-----------------+
107    | 2MB-c1            | 2                     | 1024KB          | 0KB             |
108    +-------------------+-----------------------+-----------------+-----------------+
109    | 4MB-c1            | 2                     | 1024KB          | 2048KB          |
110    +-------------------+-----------------------+-----------------+-----------------+
111    | 8MB [^]           | 2                     | 1024KB          | 6144KB          |
112    +-------------------+-----------------------+-----------------+-----------------+
113    | 16MB [^]          | 2                     | 1024KB          | 14336KB         |
114    +-------------------+-----------------------+-----------------+-----------------+
115
116    -  [^] Support for 8MB & 16MB flash size is not present in all ESP8266 SDKs. If your SDK doesn't support these flash sizes, use ``--flash_size 4MB``.
117
118.. only:: not esp8266
119
120    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 {IDF_TARGET_NAME} will not work correctly.
121