1{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32p4="GPIO35"} 2 3{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46", esp32p4="GPIO36"} 4 5{IDF_TARGET_BOOTLOADER_OFFSET:default="0", esp32="1000", esp32s2="1000", esp32p4="2000"} 6 7.. _boot-mode: 8 9Boot Mode Selection 10=================== 11 12This guide explains how to select the boot mode correctly and describes the boot log messages of {IDF_TARGET_NAME}. 13 14.. only:: esp8266 15 16 On many development boards with built-in USB/Serial, this is done for you and ``esptool`` can automatically reset the board into bootloader mode. For other configurations, you will need to follow these steps: 17 18 Required Pins 19 ------------- 20 21 The following ESP8266 pins must be in a known state for either normal (flash boot) or serial bootloader operation. Most development boards or modules make necessary connections already, internally: 22 23 +--------+--------------------------------------------------------------------------------------------------------------------+ 24 | GPIO | State | 25 +========+====================================================================================================================+ 26 | 15 | Pulled Low/GND (directly connected to GND, or external pull-down resistor) | 27 +--------+--------------------------------------------------------------------------------------------------------------------+ 28 | 2 | Pull-up resistor High/VCC, or No Connection (pin has internal weak pullup, external pullup resistor is optional) | 29 +--------+--------------------------------------------------------------------------------------------------------------------+ 30 31 If these pins are set differently to shown, nothing on the ESP8266 will work as expected. See `ESP8266 Pin List document <https://www.espressif.com/en/support/documents/technical-documents?keys=ESP8266+Pin+List>`__ to see what boot modes are enabled for different pin combinations. 32 33 When the ESP8266 goes into serial bootloader mode, the Boot ROM switches GPIO2 to an output and the UART TX signal is also output to this pin. For this reason GPIO2 should not be directly connected to VCC. Similarly, make sure GPIO2 is not connected to another peripheral where this may cause an issue when in download mode. 34 35 Select Bootloader Mode 36 ---------------------- 37 38 The ESP8266 will enter the serial bootloader when GPIO0 is held low on reset. Otherwise it will run the program in flash. 39 40 +---------------+----------------------------------------+ 41 | GPIO0 Input | Mode | 42 +===============+========================================+ 43 | Low/GND | ROM serial bootloader for esptool | 44 +---------------+----------------------------------------+ 45 | High/VCC | Normal execution mode | 46 +---------------+----------------------------------------+ 47 48 Many configurations use a "Flash" button that pulls GPIO0 low when pressed. 49 50.. only:: not esp8266 51 52 .. warning:: 53 54 The {IDF_TARGET_NAME} has a 45k ohm internal pull-up/pull-down resistor at {IDF_TARGET_STRAP_BOOT_GPIO} (and other pins). If you want to connect a switch button to enter the boot mode, this has to be a strong pull-down. For example a 10k resistor to GND. 55 56 Information about {IDF_TARGET_NAME} strapping pins can also be found in the `{IDF_TARGET_NAME} Datasheet <https://www.espressif.com/en/support/documents/technical-documents?keys={IDF_TARGET_NAME}+datasheet>`__, section "Strapping Pins". 57 58 On many development boards with built-in USB/Serial, ``esptool.py`` can automatically reset the board into bootloader mode. For other configurations or custom hardware, you will need to check the orientation of some "strapping pins" to get the correct boot mode: 59 60 Select Bootloader Mode 61 ---------------------- 62 63 {IDF_TARGET_STRAP_BOOT_GPIO} 64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 65 66 The {IDF_TARGET_NAME} will enter the serial bootloader when {IDF_TARGET_STRAP_BOOT_GPIO} is held low on reset. Otherwise it will run the program in flash. 67 68 .. list-table:: 69 :widths: 10 25 70 :header-rows: 1 71 72 * - {IDF_TARGET_STRAP_BOOT_GPIO} Input 73 - Mode 74 * - Low/GND 75 - ROM serial bootloader for esptool 76 * - High/VCC 77 - Normal execution mode 78 79 {IDF_TARGET_STRAP_BOOT_GPIO} has an internal pullup resistor, so if it is left unconnected then it will pull high. 80 81 Many boards use a button marked "Flash" (or "BOOT" on some Espressif development boards) that pulls {IDF_TARGET_STRAP_BOOT_GPIO} low when pressed. 82 83 {IDF_TARGET_STRAP_BOOT_2_GPIO} 84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 85 86 .. only:: esp32 or esp32s2 or esp32s3 87 88 {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be either left unconnected/floating, or driven Low, in order to enter the serial bootloader. 89 90 .. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6 or esp32p4 91 92 {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of {IDF_TARGET_STRAP_BOOT_2_GPIO} = 0 and {IDF_TARGET_STRAP_BOOT_GPIO} = 0 is invalid and will trigger unexpected behavior. 93 94 In normal boot mode ({IDF_TARGET_STRAP_BOOT_GPIO} high), {IDF_TARGET_STRAP_BOOT_2_GPIO} is ignored. 95 96 97 Other Pins 98 ^^^^^^^^^^ 99 100 .. only:: not esp32 101 102 As well as the above mentioned pins, other ones influence the serial bootloader, please consult the `{IDF_TARGET_NAME} Datasheet <https://www.espressif.com/en/support/documents/technical-documents?keys={IDF_TARGET_NAME}+datasheet>`__, section "Strapping Pins". 103 104 .. only:: esp32 105 106 As well as {IDF_TARGET_STRAP_BOOT_GPIO} and {IDF_TARGET_STRAP_BOOT_2_GPIO}, the following pins influence the serial bootloader mode: 107 108 +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 109 | GPIO | Meaning | 110 +=============+============================================================================================================================================================================================================================================================================================+ 111 | 12 (MTDI) | If driven High, flash voltage (VDD_SDIO) is 1.8V not default 3.3V. Has internal pull-down, so unconnected = Low = 3.3V. May prevent flashing and/or booting if 3.3V flash is used and this pin is pulled high, causing the flash to brownout. See the datasheet for more details. | 112 +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 113 | 15 (MTDO) | If driven Low, silences boot messages printed by the ROM bootloader. Has an internal pull-up, so unconnected = High = normal output. | 114 +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 115 116 For more information, consult the `{IDF_TARGET_NAME} Datasheet <https://www.espressif.com/en/support/documents/technical-documents?keys={IDF_TARGET_NAME}+datasheet>`__, section "Strapping Pins". 117 118.. _automatic-bootloader: 119 120Automatic Bootloader 121-------------------- 122 123``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting ``DTR`` and ``RTS`` control lines of the USB to serial converter chip, i.e., FTDI, CP210x, or CH340x. The ``DTR`` and ``RTS`` control lines are in turn connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of ``DTR`` and ``RTS`` will boot the {IDF_TARGET_NAME} into Firmware Download mode. 124 125.. note:: 126 127 When developing ``esptool.py``, keep in mind ``DTR`` and ``RTS`` are active low signals, i.e., ``True`` = pin @ 0V, ``False`` = pin @ VCC. 128 129As an example of auto-reset curcuitry implementation, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ of the ESP32 DevKitC development board: 130 131- The **Micro USB 5V & USB-UART** section shows the ``DTR`` and ``RTS`` control lines of the USB to serial converter chip connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` pins of the ESP module. 132- Some OS and/or drivers may activate ``RTS`` and or ``DTR`` automatically when opening the serial port (true only for some serial terminal programs, not ``esptool.py``), pulling them low together and holding the ESP in reset. If ``RTS`` is wired directly to ``EN`` then RTS/CTS "hardware flow control" needs to be disabled in the serial program to avoid this. 133 An additional circuitry is implemented in order to avoid this problem - if both ``RTS`` and ``DTR`` are asserted together, this doesn't reset the chip. The schematic shows this specific circuit with two transistors and its truth table. 134- If this circuitry is implemented (all Espressif boards have it), adding a capacitor between the ``EN`` pin and ``GND`` (in the 1uF-10uF range) is necessary for the reset circuitry to work reliably. This is shown in the **ESP32 Module** section of the schematic. 135- The **Switch Button** section shows buttons needed for :ref:`manually switching to bootloader <manual-bootloader>`. 136 137Make the following connections for ``esptool`` to automatically enter the bootloader of an {IDF_TARGET_NAME} chip: 138 139.. list-table:: 140 :header-rows: 1 141 142 * - ESP Pin 143 - Serial Pin 144 * - EN 145 - RTS 146 * - {IDF_TARGET_STRAP_BOOT_GPIO} 147 - DTR 148 149In Linux serial ports by default will assert RTS when nothing is attached to them. This can hold the {IDF_TARGET_NAME} in a reset loop which may cause some serial adapters to subsequently reset loop. This functionality can be disabled by disabling ``HUPCL`` (ie ``sudo stty -F /dev/ttyUSB0 -hupcl``). 150 151(Some third party {IDF_TARGET_NAME} development boards use an automatic reset circuit for ``EN`` & ``{IDF_TARGET_STRAP_BOOT_GPIO}`` pins, but don't add a capacitor on the ``EN`` pin. This results in unreliable automatic reset, especially on Windows. Adding a 1uF (or higher) value capacitor between ``EN`` pin and ``GND`` may make automatic reset more reliable.) 152 153In general, you should have no problems with the official Espressif development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases: 154 155- Your hardware does not have the ``DTR`` and ``RTS`` lines connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) 156- The ``DTR`` and ``RTS`` lines are configured differently 157- There are no such serial control lines at all 158 159.. _manual-bootloader: 160 161Manual Bootloader 162----------------- 163 164Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset). 165 166- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset a development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_BOOT_GPIO}``) and press the **EN** button (``EN`` (``CHIP_PU``)). 167- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_BOOT_GPIO}`` down. 168 169.. note:: 170 171 If esptool is able to reset the chip but for some reason the chip is not entering into bootloader mode then hold down the Boot button (or pull down ``{IDF_TARGET_STRAP_BOOT_GPIO}``) while you start esptool and keep it down during reset. 172 173.. only:: esp8266 174 175 .. _boot-log-esp8266: 176 177 Boot Log 178 -------- 179 180 The ESP8266 boot rom writes a log to the UART when booting. The timing is a little bit unusual: ``74880 baud`` (see :ref:`serial-port-settings`). 181 182 :: 183 184 ets Jan 8 2014,rst cause 1, boot mode:(3,7) 185 186 load 0x40100000, len 24236, room 16 187 tail 12 188 chksum 0xb7 189 ho 0 tail 12 room 4 190 load 0x3ffe8000, len 3008, room 12 191 tail 4 192 chksum 0x2c 193 load 0x3ffe8bc0, len 4816, room 4 194 tail 12 195 chksum 0x46 196 csum 0x46 197 198 199 Explanation 200 ^^^^^^^^^^^ 201 202 **rst_cause:** 203 204 +---------------+----------------------------------------+ 205 | Value | Meaning | 206 +===============+========================================+ 207 | 1 | power-on | 208 +---------------+----------------------------------------+ 209 | 2 | external-reset | 210 +---------------+----------------------------------------+ 211 | 4 | hardware watchdog-reset | 212 +---------------+----------------------------------------+ 213 214 215 **The first parameter of boot_mode:** 216 217 +-------------------------+----------------------------------------------+ 218 | Value | Meaning | 219 +=========================+==============================================+ 220 | 1 (eg. boot mode:(1,x)) | UART download mode (download FW into Flash) | 221 +-------------------------+----------------------------------------------+ 222 | 2 (eg. boot mode:(3,x)) | Boot from flash mode | 223 +-------------------------+----------------------------------------------+ 224 225 **chksum:** 226 227 If value of “chksum” == value of “csum”, it means flash has been read correctly during booting. 228 229 The rest of boot messages are used internally by Espressif. 230 231.. only:: not esp8266 232 233 Boot Log 234 -------- 235 236 Boot Mode Message 237 ^^^^^^^^^^^^^^^^^ 238 239 After reset, the second line printed by the {IDF_TARGET_NAME} ROM (at 115200bps) is a reset & boot mode message: 240 241 :: 242 243 ets Jun 8 2016 00:22:57 244 rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)) 245 246 247 ``rst:0xNN (REASON)`` is an enumerated value (and description) of the reason for the reset. A mapping between the hex value and each reason can be found in the `ESP-IDF source under RESET_REASON enum <https://github.com/espressif/esp-idf/blob/release/v5.2/components/esp_rom/include/{IDF_TARGET_PATH_NAME}/rom/rtc.h>`__. 248 The value can be read in {IDF_TARGET_NAME} code via the `get_reset_reason() ROM function <https://github.com/espressif/esp-idf/blob/release/v5.2/components/esp_rom/include/{IDF_TARGET_PATH_NAME}/rom/rtc.h>`__. 249 250 ``boot:0xNN (DESCRIPTION)`` is the hex value of the strapping pins, as represented in the `GPIO_STRAP register <https://github.com/espressif/esp-idf/blob/release/v5.2/components/soc/{IDF_TARGET_PATH_NAME}/include/soc/gpio_reg.h>`__. 251 252 The individual bit values are as follows: 253 254 .. only:: esp32 255 256 - ``0x01`` - GPIO5 257 - ``0x02`` - MTDO (GPIO15) 258 - ``0x04`` - GPIO4 259 - ``0x08`` - GPIO2 260 - ``0x10`` - GPIO0 261 - ``0x20`` - MTDI (GPIO12) 262 263 .. only:: not esp32 264 265 - ``0x04`` - {IDF_TARGET_STRAP_BOOT_2_GPIO} 266 - ``0x08`` - {IDF_TARGET_STRAP_BOOT_GPIO} 267 268 If the pin was high on reset, the bit value will be set. If it was low on reset, the bit will be cleared. 269 270 A number of boot mode strings can be shown depending on which bits are set: 271 272 - ``DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)`` or ``DOWNLOAD(USB/UART0)`` - {IDF_TARGET_NAME} is in download flashing mode (suitable for esptool) 273 - ``SPI_FAST_FLASH_BOOT`` - This is the normal SPI flash boot mode. 274 - Other modes (including ``SPI_FLASH_BOOT``, ``SDIO_REI_FEO_V1_BOOT``, ``ATE_BOOT``) may be shown here. This indicates an unsupported boot mode has been selected. 275 Consult the strapping pins shown above (in most cases, one of these modes is selected if {IDF_TARGET_STRAP_BOOT_2_GPIO} has been pulled high when {IDF_TARGET_STRAP_BOOT_GPIO} is low). 276 277 .. only:: esp32 278 279 .. note:: 280 281 ``GPIO_STRAP`` register includes GPIO 4 but this pin is not used by any supported boot mode and be set either high or low for all supported boot modes. 282 283 284 Later Boot Messages 285 ^^^^^^^^^^^^^^^^^^^ 286 287 Later output from the ROM bootloader depends on the strapping pins and 288 the boot mode. Some common output includes: 289 290 Early Flash Read Error 291 """""""""""""""""""""" 292 293 :: 294 295 flash read err, {IDF_TARGET_BOOTLOADER_OFFSET} 296 297 This fatal error indicates that the bootloader tried to read the software bootloader header at address 0x{IDF_TARGET_BOOTLOADER_OFFSET} but failed to read valid data. Possible reasons for this include: 298 299 .. list:: 300 301 - There isn't actually a bootloader at offset 0x{IDF_TARGET_BOOTLOADER_OFFSET} (maybe the bootloader was flashed to the wrong offset by mistake, or the flash has been erased and no bootloader has been flashed yet.) 302 - Physical problem with the connection to the flash chip, or flash chip power. 303 - Flash encryption is enabled but the bootloader is plaintext. Alternatively, flash encryption is disabled but the bootloader is encrypted ciphertext. 304 305 :esp32: - Boot mode accidentally set to ``HSPI_FLASH_BOOT``, which uses different SPI flash pins. Check {IDF_TARGET_STRAP_BOOT_2_GPIO} (see above). 306 :esp32: - VDDSDIO has been enabled at 1.8V (due to MTDI/GPIO12, see above), but this flash chip requires 3.3V so it's browning out. 307 308 309 Software Bootloader Header Info 310 """"""""""""""""""""""""""""""" 311 312 .. only:: esp32 313 314 :: 315 316 configsip: 0, SPIWP:0x00 317 clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 318 mode:DIO, clock div:1 319 320 321 .. only:: not esp32 322 323 :: 324 325 SPIWP:0xee 326 mode:DIO, clock div:1 327 328 329 This is normal boot output based on a combination of eFuse values and information read from the bootloader header at flash offset 0x{IDF_TARGET_BOOTLOADER_OFFSET}: 330 331 .. list:: 332 333 :esp32: - ``configsip: N`` indicates SPI flash config: 334 335 :esp32: - 0 for default SPI flash 336 :esp32: - 1 if booting from the HSPI bus (due to eFuse configuration) 337 :esp32: - Any other value indicates that SPI flash pins have been remapped via eFuse (the value is the value read from eFuse, consult :ref:`espefuse docs <espefuse>` to get an easier to read representation of these pin mappings). 338 339 - ``SPIWP:0xNN`` indicates a custom ``WP`` pin value, which is stored in the bootloader header. This pin value is only used if SPI flash pins have been remapped via eFuse (as shown in the ``configsip`` value). 340 All custom pin values but WP are encoded in the configsip byte loaded from eFuse, and WP is supplied in the bootloader header. 341 :esp32: - ``clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00`` Custom GPIO drive strength values for SPI flash pins. These are read from the bootloader header in flash. Not currently supported. 342 - ``mode: AAA, clock div: N``. SPI flash access mode. Read from the bootloader header, correspond to the ``--flash_mode`` and ``--flash_freq`` arguments supplied to ``esptool.py write_flash`` or ``esptool.py elf2image``. 343 - ``mode`` can be DIO, DOUT, QIO, or QOUT. *QIO and QOUT are not supported here*, to boot in a Quad I/O mode the ROM bootloader should load the software bootloader in a Dual I/O mode and then the ESP-IDF software bootloader enables Quad I/O based on the detected flash chip mode. 344 - ``clock div: N`` is the SPI flash clock frequency divider. This is an integer clock divider value from an 80MHz APB clock, based on the supplied ``--flash_freq`` argument (ie 80MHz=1, 40MHz=2, etc). 345 The ROM bootloader actually loads the software bootloader at a lower frequency than the flash_freq value. The initial APB clock frequency is equal to the crystal frequency, so with a 40MHz crystal the SPI clock used to load the software bootloader will be half the configured value (40MHz/2=20MHz). 346 When the software bootloader starts it sets the APB clock to 80MHz causing the SPI clock frequency to match the value set when flashing. 347 348 Software Bootloader Load Segments 349 """"""""""""""""""""""""""""""""" 350 351 :: 352 353 load:0x3fff0008,len:8 354 load:0x3fff0010,len:3680 355 load:0x40078000,len:8364 356 load:0x40080000,len:252 357 entry 0x40080034 358 359 These entries are printed as the ROM bootloader loads each segment in the software bootloader image. The load address and length of each segment is printed. 360 361 You can compare these values to the software bootloader image by running ``esptool.py --chip {IDF_TARGET_PATH_NAME} image_info /path/to/bootloader.bin`` to dump image info including a summary of each segment. Corresponding details will also be found in the bootloader ELF file headers. 362 363 If there is a problem with the SPI flash chip addressing mode, the values printed by the bootloader here may be corrupted. 364 365 The final line shows the entry point address of the software bootloader, where the ROM bootloader will call as it hands over control. 366
