Articles / Embedded

  • esp32
  • esp-idf
  • strapping-pins
  • gpio
  • boot
  • debugging

Why Your ESP32 Fails to Boot When a GPIO Is Pulled the Wrong Way

Your board runs fine on the bench, then you wire a sensor or a button to a spare GPIO and it stops booting. No crash, no panic, just a serial log saying "waiting for download" or complaining about an invalid flash header. The firmware did not change. The pin did.

The cause is almost always a strapping pin. The chip reads a handful of GPIOs at the instant it leaves reset, and whatever your circuit is doing to them at that moment decides how it boots.

What the chip looks at before your code exists

On the classic ESP32 there are five strapping pins. The ROM bootloader samples them on reset, before any of your firmware has run, so no amount of pinMode() can save you. They are:

  • GPIO0: low at reset means "enter serial download mode"; high means boot from flash.
  • GPIO2: needs to be low (or floating) to enter download mode, and is best left alone otherwise.
  • GPIO5: affects SDIO slave timing; has an internal pull-up.
  • GPIO12 (MTDI): selects the flash voltage; has an internal pull-down.
  • GPIO15 (MTDO): if low, silences the boot log on UART0; has an internal pull-up.

The internal pulls matter. A pin you leave floating still has a defined default, and your external circuit only has to be stronger than it to change the result.

The two failures you will actually see

Most reports collapse into two symptoms, and the boot log tells you which.

GPIO0 held low gives you download mode. The log shows something like this, then nothing:

rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2))
waiting for download

Your flash is fine and your app is intact; the chip is simply waiting for esptool. A button, a sensor output or a pull-down on GPIO0 is the usual culprit. A normal boot shows a different boot: value, typically 0x13 (SPI_FAST_FLASH_BOOT).

GPIO12 and the flash voltage trap

Hang on, why does a pin called MTDI break flash reads? Because GPIO12 at reset selects the voltage of the internal regulator that powers the flash (VDD_SDIO). Low gives 3.3 V; high gives 1.8 V.

If your module has 3.3 V flash and something pulls GPIO12 high at reset, the flash gets the wrong voltage. You then see errors such as these:

flash read err, 1000
ets_main.c 371
invalid header: 0xffffffff

Typical causes are a pull-up on a pin you thought was free, a peripheral that drives the line high while it powers up, or a JTAG adapter left attached. Most modules with 1.8 V flash have the voltage burned into an eFuse so the strap is ignored; if you are unsure, check the module datasheet before touching eFuses, because they are one-way.

How to confirm it is a strapping problem

Do not guess. Run through these steps:

  1. Disconnect everything from the five pins above and power-cycle. If it boots, you have your answer.
  2. Read the first lines of the serial log at 115200 baud. The boot: mode and any flash errors come from the ROM, so they appear even with broken firmware.
  3. Reconnect peripherals one at a time, resetting each time.
  4. If a scope or logic analyser is handy, watch the pin during power-up, not afterwards. A line that settles correctly 50 ms late is still wrong at the moment of sampling.

Fixes that hold up

The cheapest fix is moving the peripheral to a pin that is not a strapping pin. The other options, in rough order of preference:

  • Use a pin with no boot role. Avoid GPIO6 to GPIO11 too, which are wired to the SPI flash on most modules.
  • Add a resistor so the external level agrees with the strap you want, for example a 10 k pull-up on a button that sits on GPIO0 (the button then pulls low only when pressed, which is what you want, but also means you must not hold it at reset).
  • Gate the peripheral with a transistor or load switch that is off during reset, then enable it from firmware.
  • Put a series resistor between the pin and a device that drives its output at power-up, so the internal pull can win.

Notice what is not on the list: fixing it in software. By the time your code runs, the decision was made.

Other chips, other pins

The set differs per chip. The ESP32-S3 and ESP32-C3, for instance, use different strapping pins (the S3 includes GPIO0, GPIO3, GPIO45 and GPIO46; the C3 uses GPIO2, GPIO8 and GPIO9). Do not carry a pin map from one variant to another; the strapping table in the datasheet for your exact chip is a one-minute read that saves an evening of puzzling.

One last quirk: on dev boards, the auto-reset circuit on the USB-serial chip toggles GPIO0 and EN through transistors. If your own wiring loads those lines, flashing can fail even though a normal boot works.