ESP32 Deep Dive

Beyond the Datasheet

Most people interact with ESP32 chips through one command: esptool.py write_flash. It works, the LED blinks, you move on. This document is for when it doesn't work, or when you need to do something more interesting than blink the LED, or when you want to understand why an ESP32-C3 has its bootloader at 0x0 while ESP32-classic has it at 0x1000.

Scope: ESP32 family chips (classic, S2, S3, C3, C5, C6, H2, P4) talking to a host computer over UART or native USB. Reference tooling is esptool.py v4.x, espefuse.py, espsecure.py, and the ESP-IDF wrapper idf.py. Where chip variants differ, called out explicitly.

Boot Modes & Strap Pins

Every ESP32 chip samples a handful of GPIO pins in the first few microseconds after reset comes high. Those samples decide whether the chip boots from flash, enters the UART download bootloader, or does something weird. If you have flashing problems and the wiring looks right, it's almost always strap pins.

The strap pins per chip

Boot strap is sampled at the rising edge of CHIP_PU (also called EN or RST). The sample is latched: changing the pin after the chip has come out of reset does nothing for boot mode. To re-enter download mode you must reset again.

The auto-reset circuit

Dev boards like NodeMCU, Wemos, and ESP32-DevKitC all carry the same little NPN-transistor circuit so esptool can flash without you touching a button. It uses the two RS-232 modem control lines that USB-serial chips expose: DTR and RTS. The trick is that the transistors invert the lines, and they're wired so that asserting DTR alone or RTS alone does nothing.

    USB-serial            transistor pair             ESP32
    ──────────            ───────────────             ─────

      DTR  ────┬─────┐                                EN
                │     │ Q1                              ▲
                │     ├──── BASE                        │
                │     │                                 │
      RTS  ──┐ │  ┌──┴── BASE  Q2                    GPIO0
              │ │  │                                    ▲
              └─┼──┘                                    │
                │                                       │
                └───────────────────────────────────────┘

    Truth table  (DTR/RTS at the chip pin, after inversion)

      DTR=H  RTS=H   →   EN=H, GPIO0=H   // normal run
      DTR=L  RTS=L   →   EN=H, GPIO0=H   // normal run
      DTR=H  RTS=L   →   EN=L, GPIO0=H   // reset only
      DTR=L  RTS=H   →   EN=H, GPIO0=L   // boot only

The cross-wiring is intentional. Each line by itself does nothing useful: only the transition from DTR=H,RTS=L (reset asserted) to DTR=L,RTS=H (reset released, GPIO0 still pulled low) actually triggers download mode. Meanwhile RTS=H,DTR=H at idle keeps both pins high so the chip boots normally. This is why opening the port in a normal terminal doesn't accidentally reset the chip.

esptool reset sequences

esptool exposes the reset behaviour through --before and --after. Each name corresponds to a specific dance on DTR/RTS.

Manual entry into download mode

When the auto-reset circuit isn't there, doesn't work, or you've cut its traces, you do it by hand. The sequence on every ESP32 variant is the same:

1. Hold BOOT Press and hold the boot button (GPIO0 on classic / S2 / S3, GPIO9 on RISC-V variants).
2. Pulse EN While still holding BOOT, press and release the EN/RST button. Some boards need you to hold EN for a half-second.
3. Release BOOT Wait at least 100ms after releasing EN, then release BOOT.
4. Verify Open a terminal at 115200 baud. The ROM bootloader on classic ESP32 prints waiting for download. RISC-V variants print nothing by default but respond to esptool.py chip_id.

SLIP Wire Protocol

esptool talks to the ROM bootloader using a binary command protocol over UART, framed with SLIP (Serial Line Internet Protocol, RFC 1055). Reading a SLIP-framed esptool exchange from a logic analyzer is one of the fastest ways to understand what's happening when uploads fail.

SLIP framing rules

Each packet is delimited by the 0xC0 byte (END). Inside a packet, two bytes need escaping: the END byte itself becomes 0xDB 0xDC, and the escape byte 0xDB becomes 0xDB 0xDD.

slip framing
// raw payload
A1 B2 C0 D4 DB F6

// after slip escaping (with END framing)
C0 A1 B2 DB DC D4 DB DD F6 C0
^^      ^^^^^      ^^^^^      ^^
|       escape     escape    end
start   for C0     for DB    delimiter

Decode is the reverse: read until you see an unescaped C0, then walk the buffer replacing escape pairs back to their original bytes. Because escape bytes can never appear unescaped inside a packet, framing is unambiguous even if you join mid-stream and miss the start.

Command packet structure

esptool command packet (pre-slip-encoding)
 0       1       2       3       4       5       6       7
+-------+-------+-------+-------+-------+-------+-------+-------+
| DIR   | CMD   | SIZE (LE)     | CHECKSUM (LE32)             |
+-------+-------+-------+-------+-------+-------+-------+-------+
| DATA ...                                                       |
+---------------------------------------------------------------+

  DIR      0x00 = request, 0x01 = response
  CMD      one of the command opcodes (table below)
  SIZE     uint16, little-endian, length of DATA in bytes
  CHECKSUM uint32, little-endian, XOR-fold of DATA bytes with seed 0xEF
           (only used by FLASH_DATA / MEM_DATA; ignored otherwise)
  DATA     command-specific payload

// the entire structure above is then SLIP-framed before transmit

Command opcodes

The SYNC handshake

Every esptool session starts with sync. The host sends a fixed 36-byte SYNC payload up to seven times (with retries on no response). The chip echoes back, and from the echo esptool fingerprints which chip variant it's talking to.

sync payload
// 36 bytes total, sent as the DATA of a SYNC command (0x08)
07 07 12 20                                       // magic prefix
55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55   // 32 bytes of 0x55
55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55

// timing
// host sleeps ~100ms between sync attempts to let chip latch baud rate
// chip echoes empty SYNC response when it accepts

The eight 0x55 bytes (binary 01010101) are deliberate: alternating bits help a UART auto-baud routine lock onto the host's baud rate. ESP32 ROMs do auto-baud detection on the first SYNC, which is why esptool can connect at any rate from 9600 up to 115200 without telling the chip in advance.

A complete sync + chip_id capture

logic analyzer view, host → chip in green
// host sends SYNC
C0 00 08 24 00 00 00 00 00 07 07 12 20 55 55 55 55 ... 55 C0
                                    ^ data: 36 bytes

// chip responds (echoes 8 trailing 0x55, status 0/0)
C0 01 08 04 00 00 00 00 00 00 00 00 00 C0

// host sends READ_REG against EFUSE_BLK0_RDATA3 (0x3FF5A00C on classic)
C0 00 0A 04 00 00 00 00 00 0C A0 F5 3F C0
                                    ^ register address, LE32

// chip responds with the register value (32-bit LE)
C0 01 0A 04 00 A4 7C 24 BC 00 00 00 00 C0
                  ^ value goes in the "value" field, not data

READ_REG and WRITE_REG don't use the data field for results. The 32-bit register value comes back in what would be the checksum slot of the response packet. Awkward, but that's how the protocol grew.

The Stub Loader

The ROM bootloader on every ESP32 chip is fixed silicon-or-mask-ROM and can't be patched. It's also pretty minimal: no compression, no faster baud, no MD5 verification, slow flash writes. To work around this, esptool uploads a small program to RAM at the start of every session called the stub loader. The stub re-implements the same protocol but with extra commands and fewer bugs.

Stub upload sequence

    HOST                                        CHIP (ROM)
      │                                            │
      │  SYNC ──────────────────────────────────▶ │
      │  ◀──────────────────────────────── ack    │
      │                                            │
      │  MEM_BEGIN(addr=stub.text_addr,            │
      │            size=stub.text_size,            │
      │            blocks=N, blocksize=4096) ────▶ │
      │  ◀──────────────────────────────── ack    │
      │                                            │
      │  MEM_DATA(seq=0, payload=text_block_0) ─▶ │
      │  MEM_DATA(seq=1, payload=text_block_1) ─▶ │
      │  ...                                       │
      │                                            │
      │  MEM_BEGIN(addr=stub.data_addr, ...) ────▶ │
      │  MEM_DATA(seq=0, payload=data_block_0) ─▶ │
      │  ...                                       │
      │                                            │
      │  MEM_END(entry=stub.entry_addr) ────────▶ │
      │                                            │  jump to entry
      │                                            │  STUB now running
      │  ◀──── 4 bytes "OHAI" over UART          │  prints OHAI
      │                                            │
      │  CHANGE_BAUDRATE(921600) ────────────────▶ │
      │  ◀───────────────────────────────── ack    │
      │                                            │
      │  FLASH_DEFL_BEGIN / FLASH_DEFL_DATA ─────▶ │  fast path now

The OHAI string is literally that: four bytes 0x4F 0x48 0x41 0x49, sent unsolicited by the stub on entry. esptool reads four bytes and either matches the magic and continues, or assumes the upload failed.

What the stub adds

Where the stub lives in RAM

Stub addresses are chip-specific because each variant has different IRAM/DRAM layouts and the stub has to fit somewhere that won't collide with the ROM bootloader's own variables. esptool ships pre-compiled stubs (one per chip) embedded as hex blobs in the source.

Skipping the stub

Two situations want raw ROM mode: when the stub itself is misbehaving (rare, but happens on early production chips and on some clones), and when you're testing pure ROM bootloader behavior. Pass --no-stub to esptool. You lose compression, MD5, fast baud, and read_flash. Most operations still work, just slower.

stub vs no-stub
esptool.py --port /dev/ttyUSB0 write_flash 0x10000 firmware.bin
# default: uploads stub, uses compressed write at 460800 baud

esptool.py --no-stub --port /dev/ttyUSB0 write_flash 0x10000 firmware.bin
# raw ROM: uncompressed, 115200 baud max, no md5 verify after

Flash Geometry

Where things live on the SPI flash chip is one of the most chip-variant-specific aspects of the ESP32 family. The flash itself is a generic 25-series SPI chip (Winbond, GigaDevice, ISSI, XMC), but the address at which the bootloader expects to start is hardcoded into the silicon ROM. Putting the bootloader at the wrong offset means a chip that successfully accepts the write but never boots.

Bootloader offset by chip

Standard ESP-IDF layout

classic ESP32, default 4MB flash
0x000000  ┌─────────────────────────────────┐  // reserved (secure boot digest area)
          │  empty / digest                 │
0x001000  ├─────────────────────────────────┤
          │  2nd-stage bootloader             │  // bootloader.bin (~25KB)
          │                                 │
0x008000  ├─────────────────────────────────┤
          │  partition table                  │  // 4KB, ends with MD5 entry
0x009000  ├─────────────────────────────────┤
          │  nvs (data/wifi)                │  // 24KB key-value store
0x00f000  ├─────────────────────────────────┤
          │  phy_init                        │  // 4KB RF calibration
0x010000  ├─────────────────────────────────┤
          │                                 │
          │  factory app (or ota_0)          │  // 1MB+, your code
          │                                 │
0x110000  ├─────────────────────────────────┤
          │  ota_1 (if dual-OTA layout)      │  // matches ota_0 size
          │                                 │
0x210000  ├─────────────────────────────────┤
          │  spiffs / littlefs / userdata    │
          │                                 │
0x3FF000  ├─────────────────────────────────┤
          │  otadata                         │  // 8KB, holds active OTA slot
0x400000  └─────────────────────────────────┘  // end of 4MB flash

The partition table

At 0x8000 (default; configurable in menuconfig) lives a 4KB partition table. It's a list of 32-byte entries, terminated by an MD5-checksum entry. ESP-IDF reads it on boot to figure out where every other partition lives.

partition table entry layout
 0       1       2       3       4       5       6       7
+-------+-------+-------+-------+-------+-------+-------+-------+
| MAGIC (LE16)  | TYPE  | SUB   | OFFSET (LE32)             |
+-------+-------+-------+-------+-------+-------+-------+-------+
| SIZE (LE32)                  | LABEL (16 bytes, null-padded)
+-------+-------+-------+-------+-------+-------+-------+-------+
                                | FLAGS (LE32)              |
                                +-------+-------+-------+-------+

  MAGIC   0xAA50  (regular entry) or 0xEBEB (md5 trailer)
  TYPE    0x00 = app, 0x01 = data, 0x40-0xFE = custom
  SUB     subtype within type. app: 0x00=factory, 0x10/0x11=ota_0/1
                              data: 0x00=otadata, 0x01=phy, 0x02=nvs,
                                    0x82=spiffs, 0x83=littlefs
  FLAGS   bit 0 = encrypted, bit 1 = readonly

Reading the partition table from a running chip

dump partition table
esptool.py --port /dev/ttyUSB0 read_flash 0x8000 0x1000 partitions.bin
parttool.py -q get_partition_info --partition-table-file partitions.bin --info name offset size

# or via the IDF python helper
python $IDF_PATH/components/partition_table/gen_esp32part.py partitions.bin

# typical output
# nvs,data,nvs,0x9000,24K,
# phy_init,data,phy,0xf000,4K,
# factory,app,factory,0x10000,1M,
# spiffs,data,spiffs,0x110000,1M,

Flash mode, frequency, and size

These three parameters live in the bootloader image header and tell the ROM how to talk to the SPI flash chip. Wrong values are the second-most-common cause of "boots once, won't boot again" symptoms (the first is bad partition tables).

setting flash params at write time
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z \
  --flash_mode dio --flash_freq 40m --flash_size 4MB \
  0x1000  bootloader.bin \
  0x8000  partitions.bin \
  0x10000 firmware.bin

# detect what the flash chip says about itself
esptool.py flash_id
# Manufacturer: ef    (Winbond)
# Device:       4017  (W25Q64)
# Detected flash size: 8MB

Read, Write & Verify

The everyday operations. The flags below mostly compose: --port, --baud, --chip, --before, --after apply to all of them.

Common flags

chip_id, flash_id, read_mac

identification commands
esptool.py chip_id
# Chip is ESP32-D0WD-V3 (revision v3.0)
# Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse
# Crystal is 40MHz
# MAC: 24:6f:28:ab:cd:ef

esptool.py flash_id
# Manufacturer: ef
# Device:       4016
# Detected flash size: 4MB

esptool.py read_mac
# MAC: 24:6f:28:ab:cd:ef
# BASE MAC, WIFI_STA, WIFI_AP, BT, ETH all derived

Each ESP32 has a single 48-bit base MAC burned into eFuse at the factory. The four interface MACs (Wi-Fi STA, Wi-Fi AP, Bluetooth, Ethernet) are derived deterministically from base MAC plus a small offset. Don't randomize them; they're meant to be unique per silicon.

write_flash

write_flash with all the flags
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 write_flash \
  -z                          # compress with zlib (stub only)
  --flash_mode dio              # SPI mode
  --flash_freq 40m              # SPI clock
  --flash_size detect           # let chip report
  --erase-all                  # erase whole chip first (optional)
  --verify                      # MD5 check after write
  --encrypt                     # encrypt during write (flash encryption enabled chips)
  --ignore-flash-encryption-efuse-setting   # override safety check
  0x1000  bootloader.bin
  0x8000  partitions.bin
  0x10000 firmware.bin
  0x310000 spiffs.bin

The pairs of address file at the end can repeat as many times as you want. esptool sorts them by address before sending and writes each region with FLASH_BEGIN / FLASH_DATA / FLASH_END (or the DEFL variants under -z).

read_flash

read flash to file
# dump entire 4MB flash
esptool.py read_flash 0 0x400000 dump.bin

# dump just the partition table
esptool.py read_flash 0x8000 0x1000 parts.bin

# dump the running firmware partition (find offset+size from partition table first)
esptool.py read_flash 0x10000 0x100000 app.bin

# skip the read of unprogrammed (0xFF) sectors to save time
esptool.py read_flash 0 ALL flash_dump.bin
# "ALL" reads up to the detected flash size

verify_flash

verify without rewriting
esptool.py verify_flash 0x10000 firmware.bin
# Verifying 0x100000 (1048576) bytes @ 0x00010000 in flash against firmware.bin...
# -- verify OK (digest matched)

# mismatch case
# -- verify FAILED: 0x40 (64) bytes differ at @ 0x00012E40
# first byte differs: file=0xA1 flash=0xFF

verify_flash uses the SPI_FLASH_MD5 stub command to ask the chip for an MD5 hash of a region, then compares against an MD5 it computes locally over the file. No data is read back, just the digest. This is much faster than read-then-compare for large regions.

erase_flash, erase_region

erasing
# whole-chip erase (issues SPI command 0xC7)
esptool.py erase_flash
# takes 8-30s depending on flash size

# just the NVS partition (24KB starting at 0x9000)
esptool.py erase_region 0x9000 0x6000
# both args must be 4KB-aligned (one sector)

# nuke OTA data so chip falls back to factory
esptool.py erase_region 0xd000 0x2000

Image Format & elf2image

The .bin file you flash is not just a copy of your .elf. It's a structured container with a header, a list of segments, and a checksum (and on newer chips, a SHA-256). The conversion happens via esptool.py elf2image, which the IDF build system runs automatically.

Image header layout

esp32 firmware image header (24 bytes)
 0       1       2       3       4       5       6       7
+-------+-------+-------+-------+-------+-------+-------+-------+
| MAGIC | SEG#  | FMODE | FSF   | ENTRY POINT (LE32)        |
+-------+-------+-------+-------+-------+-------+-------+-------+
| WP_PIN| CLK_DRV / Q_DRV ...        | CHIP_ID (LE16) |       |
+-------+-------+-------+-------+-------+-------+-------+-------+
| MIN_REV...                | MAX_REV ...                | RESVD |
+-------+-------+-------+-------+-------+-------+-------+-------+
| HASH_APPENDED                                                  |
+-------+

  MAGIC          0xE9
  SEG#           number of segments that follow
  FMODE          flash mode (0=qio, 1=qout, 2=dio, 3=dout, 4=opi)
  FSF            high nibble = flash size (0=1MB, 1=2MB, ..., 4=16MB)
                 low nibble  = flash freq (0=40m, 1=26m, 2=20m, 0xF=80m)
  ENTRY POINT    32-bit jump address after image is loaded
  CHIP_ID        0=ESP32, 2=S2, 5=C3, 9=S3, 12=C2, 13=C6, 16=H2, ...
  HASH_APPENDED  1 = SHA-256 follows after last segment

Segment layout

segment (variable length)
+-------+-------+-------+-------+
| LOAD ADDR (LE32)            |
+-------+-------+-------+-------+
| DATA LEN (LE32)             |
+-------+-------+-------+-------+
| DATA bytes ...                              |
+--------------------------------+

  // repeats SEG# times
  // padded so total image length is multiple of 16 bytes
  // 1-byte XOR checksum at the next 16-byte boundary - 1
  // (last byte of the padded image)
  // then optional 32-byte SHA-256 if HASH_APPENDED
  // then optional signature block if signed (secure boot)

elf2image conversion

elf2image
esptool.py --chip esp32 elf2image \
  --flash_mode dio --flash_freq 40m --flash_size 4MB \
  --min-rev 0 --max-rev 0x100 \
  -o firmware.bin firmware.elf

# inspect the resulting image
esptool.py image_info firmware.bin
# File size: 1234560 bytes
# Image version: 1
# Entry point: 0x40080a44
# Segments: 5
# Segment 1: len 0x024df0 load 0x3f400020 file_offs 0x00000018 [DROM]
# Segment 2: len 0x00400 load 0x3ffb0000 file_offs 0x00024e10 [BYTE_ACCESSIBLE,DRAM]
# Segment 3: len 0x094a0 load 0x3ffb0400 file_offs 0x00025218 [DRAM]
# Segment 4: len 0x06bcc load 0x40080000 file_offs 0x0002e6c0 [IRAM]
# Segment 5: len 0x1604c load 0x400d0020 file_offs 0x00035294 [IROM]
# Checksum: 0xa1 (valid)
# Validation hash: SHA256 fb29... (valid)

Memory regions in segment names

merge_bin

For factory programmers, OTA cloud uploads, or anywhere that wants a single contiguous image, merge_bin stitches the bootloader, partition table, app, and any other regions into one file you can flash at offset 0 (or wherever the chip's bootloader expects).

merge_bin
esptool.py --chip esp32 merge_bin -o merged.bin \
  --flash_mode dio --flash_freq 40m --flash_size 4MB \
  0x1000  bootloader.bin \
  0x8000  partitions.bin \
  0x10000 app.bin

# now flash the single file at offset 0
esptool.py write_flash 0x0 merged.bin

# or pad to full flash size (good for production imaging)
esptool.py merge_bin -o factory.bin --fill-flash-size 4MB \
  0x1000 bootloader.bin 0x8000 partitions.bin 0x10000 app.bin

eFuse & Security

eFuses are one-time-programmable (OTP) bits inside every ESP32 chip. They store the factory MAC address, the chip revision, calibration values, and a small set of user-burnable security keys and flags. Once a fuse is burned (set to 1), it cannot be unburned. Misusing espefuse.py is a fast way to brick a chip permanently.

eFuse layout

S2/S3/C3/etc. expand this to BLK0-BLK10 with multiple key slots, key-purpose bits, and dedicated digest blocks. The principle is the same: read-or-write protectable banks of OTP bits.

espefuse.py

summary: read every eFuse
espefuse.py --port /dev/ttyUSB0 summary
### EFUSE_BLK0 fields ###
# MAC                : 24:6f:28:ab:cd:ef
# CHIP_VER_REV1      : 1
# CHIP_VERSION       : 0
# CHIP_PACKAGE       : 1
# UART_DOWNLOAD_DIS  : False  R/W (0b0)
# DISABLE_JTAG       : False  R/W (0b0)
# FLASH_CRYPT_CNT    : 0      R/W (0b0000000)
# ABS_DONE_0         : False  R/W (0b0)   // secure boot v1 enable
# ...

burn fuses (DESTRUCTIVE - irreversible)
# burn an arbitrary user fuse
espefuse.py burn_efuse WR_DIS 0x1

# burn a key into a key block
espefuse.py burn_key BLOCK1 flash_encryption_key.bin

# burn flash encryption key + enable + lock down (full deployment)
espefuse.py burn_key BLOCK1 flash_enc_key.bin
espefuse.py burn_efuse FLASH_CRYPT_CNT 0x7
espefuse.py burn_efuse FLASH_CRYPT_CONFIG 0xF
espefuse.py write_protect_efuse FLASH_CRYPT_CNT  # can no longer disable

# raw 256-bit data into a user block
espefuse.py burn_block_data BLOCK3 customer_data.bin

# lock specific fuses against further changes
espefuse.py read_protect_efuse BLOCK1   # key can never be read out
espefuse.py write_protect_efuse BLOCK1  # key can never be re-written

espsecure.py

Where espefuse deals with the chip side of security, espsecure is the host-side counterpart: it generates keys, signs images, and prepares encrypted payloads.

secure boot v2 workflow
# generate signing key (RSA-3072 for V2, ECDSA also supported)
espsecure.py generate_signing_key --version 2 secure_boot_signing_key.pem

# compute the public key digest (this is what gets burned to eFuse)
espsecure.py digest_sbv2_public_key \
  --keyfile secure_boot_signing_key.pem \
  --output sb_public_digest.bin

# sign an application image
espsecure.py sign_data --version 2 \
  --keyfile secure_boot_signing_key.pem \
  --output firmware_signed.bin firmware.bin

# verify a signed image (no chip needed)
espsecure.py verify_signature --version 2 \
  --keyfile secure_boot_signing_key.pem firmware_signed.bin

flash encryption workflow
# generate AES-256 key
espsecure.py generate_flash_encryption_key --keylen 256 fe_key.bin

# encrypt a binary using that key (offset matters - tweak depends on it)
espsecure.py encrypt_flash_data \
  --keyfile fe_key.bin \
  --address 0x10000 \
  --output firmware_enc.bin firmware.bin

# decrypt for inspection
espsecure.py decrypt_flash_data \
  --keyfile fe_key.bin \
  --address 0x10000 \
  --output firmware_dec.bin firmware_enc.bin

Secure boot V1 vs V2

ESP-IDF: idf.py

Before idf.py, an ESP-IDF build was a CMake invocation, a Python script to merge images, and a separate esptool call. The wrapper folds all of it into one CLI. Under the hood it still calls esptool; you can see the exact command with -v.

Lifecycle commands

idf.py monitor: more than a terminal

The monitor is not just screen. It pipes the serial stream through addr2line so that addresses in panic backtraces become file:line references, decodes coredumps if you point it at the elf, recognizes esp_log color codes, and lets you trigger flash/build cycles without quitting.

monitor key bindings
Ctrl+T  Ctrl+H  help screen
Ctrl+T  Ctrl+R  reset chip (hardware EN pulse via DTR)
Ctrl+T  Ctrl+F  build & flash app, then resume monitoring
Ctrl+T  Ctrl+A  build & flash app only (no monitor break)
Ctrl+T  Ctrl+P  pause chip (suspend output)
Ctrl+T  Ctrl+Y  toggle log printing on/off
Ctrl+T  Ctrl+L  toggle timestamp prefix on each line
Ctrl+T  Ctrl+T  reset chip + enter download mode (button-less)
Ctrl+]          quit (this is also Ctrl+5 on some keyboards)

The Ctrl+T sequence exists because Ctrl+] is the GNU screen escape and they didn't want collisions. The trade-off is that anyone unfamiliar with the binding spends a minute discovering they can't quit without a kill -9. Ctrl+] is the safety hatch.

The build directory

build/ after idf.py build
build/
├── bootloader/
│   └── bootloader.bin               # 0x1000 (classic) or 0x0 (newer)
├── partition_table/
│   └── partition-table.bin          # 0x8000
├── ota_data_initial.bin             # 0xd000 if OTA
├── my_app.bin                       # the actual application image (0x10000)
├── my_app.elf                       # elf with debug symbols, for addr2line/gdb
├── my_app.map                       # linker map; use to chase symbol bloat
├── flasher_args.json                # everything esptool needs in one file
├── flash_args                       # shell-style equivalent
└── compile_commands.json            # for clangd, vscode, etc

flasher_args.json is the single source of truth for what idf.py flash will run. If you want to recreate the flash command outside of idf.py (CI, factory programmer, third-party tool), that file has every offset, mode, freq, and binary path. Read it with jq for scripting.

Serial Monitors & Discovery

Half of ESP32 troubleshooting is figuring out which /dev/ttyXXX the board mounted as, what driver it's using, and whether the host's getty has stolen it. These are the commands.

Identifying the device

Linux: USB-serial discovery
# freshly plug in the board, then
dmesg | tail -30
# [12345.678] usb 1-1.4: new full-speed USB device number 7 using ehci-pci
# [12345.789] usb 1-1.4: New USB device found, idVendor=10c4, idProduct=ea60
# [12345.789] usb 1-1.4: Product: CP2102 USB to UART Bridge Controller
# [12345.890] cp210x 1-1.4:1.0: cp210x converter detected
# [12345.901] usb 1-1.4: cp210x converter now attached to ttyUSB0

# list every serial-class device with metadata
python -m serial.tools.list_ports -v
# /dev/ttyUSB0
#     desc: CP2102 USB to UART Bridge Controller
#     hwid: USB VID:PID=10C4:EA60 SER=01234567 LOCATION=1-1.4

# udev's view of the device
udevadm info -a -n /dev/ttyUSB0 | grep -E 'idVendor|idProduct|serial'

# live USB topology
lsusb -tv

USB-serial chips found on ESP32 boards

udev rules for stable names + permissions

/etc/udev/rules.d/99-esp32.rules
# grant access to dialout group, create stable symlink
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", \
  MODE="0666", GROUP="dialout", SYMLINK+="esp32-cp210x"

SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", \
  MODE="0666", GROUP="dialout", SYMLINK+="esp32-ch340"

SUBSYSTEM=="tty", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", \
  MODE="0666", GROUP="dialout", SYMLINK+="esp32-native"

# reload
sudo udevadm control --reload-rules
sudo udevadm trigger

Then your scripts and IDE configs can use the stable /dev/esp32-cp210x path instead of guessing whether it'll be ttyUSB0 or ttyUSB2 today. The SERIAL attribute lets you distinguish two boards of the same type if you populate it with the chip's serial number.

Terminal programs comparison

JTAG, OpenOCD, GDB

For anything beyond printf debugging — single-stepping, watching memory, breaking on hardware events — you need JTAG. Espressif provides a customized OpenOCD fork that knows about Xtensa LX6/LX7 (ESP32, S2, S3) and standard RISC-V (C3, C6, H2, P4) cores.

JTAG pin assignments

Classic ESP32 needs an external probe (FT2232H, J-Link, Olimex ARM-USB-OCD, ESP-Prog). The newer chips with built-in USB-Serial-JTAG let you skip the probe entirely: plug the board's USB-OTG port into your host and OpenOCD talks JTAG over the same USB connection that's giving you the serial console.

Launching OpenOCD

openocd against various targets
# classic ESP32 over FT2232H (ESP-Prog or generic)
openocd -f board/esp32-wrover-kit-3.3v.cfg

# ESP32-S3 over its built-in USB-JTAG
openocd -f board/esp32s3-builtin.cfg

# ESP32-C3 over its built-in USB-JTAG
openocd -f board/esp32c3-builtin.cfg

# custom: explicit interface + target chain
openocd \
  -f interface/ftdi/esp32_devkitj_v1.cfg \
  -f target/esp32.cfg \
  -c "adapter speed 20000"

# typical output
# Open On-Chip Debugger v0.12.0-esp32-20231004
# Info : ftdi: clock auto-adapt set to 10000 kHz
# Info : esp32.cpu0: hardware has 2 break/watch points
# Info : Listening on port 3333 for gdb connections
# Info : Listening on port 4444 for telnet connections

OpenOCD listens on three ports by default: 3333 for GDB remote-serial-protocol, 4444 for an interactive telnet command shell, and 6666 for tcl. The telnet shell is where you do one-off operations like halt, reset, flash erase_address 0x10000 0x100000, or mdw 0x3FF42000 16 to peek at memory.

GDB session

debug an existing build
# in one terminal: openocd
openocd -f board/esp32s3-builtin.cfg

# in another: gdb attached
xtensa-esp32s3-elf-gdb build/firmware.elf
(gdb) target remote :3333
(gdb) monitor reset halt           # OpenOCD telnet command from inside gdb
(gdb) flushregs                    # refresh after monitor reset
(gdb) hb app_main                  # hardware breakpoint (limited count)
(gdb) c                            # continue
(gdb) bt                           # once we hit, full backtrace
(gdb) info threads                 # FreeRTOS task list with names
(gdb) thread 4                     # switch to a different task
(gdb) x/64xw 0x3FFB0000           # hex dump 64 words from DRAM
(gdb) disassemble                  # show current function asm

idf.py gdb / openocd shortcuts

idf.py wrappers
# start openocd in a child process
idf.py openocd

# start openocd + gdb together, attached to the right elf
idf.py gdb

# or use the gdbgui frontend
idf.py gdbgui

# start gdb in batch mode running a script
idf.py gdb --batch --commands debug_script.gdb

Brick Recovery

The flowchart for "my ESP32 doesn't work anymore." Most apparent bricks are not actual silicon failures, they're recoverable software states.

Diagnosis tree

START: chip doesn't boot or behaves strangely

  │
  ▼
  does esptool.py chip_id work?
  ├── no  ────▶ go to "no comms" branch
  └── yes ───▶ go to "comms ok" branch


no comms branch
  │
  ├──▶ manual download mode? (hold BOOT, pulse EN)
  │      ├── now works ──▶ auto-reset circuit broken: solder, swap board, or use --before no_reset
  │      └── still fails ──▶ continue
  │
  ├──▶ different USB cable + port? swap.
  │
  ├──▶ dmesg shows USB enumeration?
  │      ├── no ──▶ dead USB-serial chip or board power, check 3.3V rail
  │      └── yes ──▶ continue
  │
  ├──▶ ROM is reachable but won't enter download:
  │      check eFuse UART_DOWNLOAD_DIS via espefuse summary IF YOU CAN STILL READ EFUSES
  │      if burnt: chip is permanently locked. recover via JTAG only if not also disabled.
  │
  └──▶ last resort: lift flash chip, reflash externally, resolder

comms ok branch
  │
  ├──▶ erase + reflash from clean source
  │      esptool.py erase_flash
  │      esptool.py write_flash 0x0 merged.bin
  │      power cycle and observe
  │
  ├──▶ still bad: check flash params (mode/freq/size) match the board
  │      esptool.py flash_id   ──▶ get manufacturer/device/size
  │      cross-reference datasheet for max freq + valid modes
  │
  ├──▶ still bad: check eFuse summary for unexpected writes
  │      espefuse.py summary | grep -i "True"
  │      anything that says SECURE_BOOT, FLASH_CRYPT, DISABLE_*
  │      that you didn't set means somebody else burned a fuse
  │
  └──▶ still bad with all known-good binaries: silicon defect or RF damage

The "weird boot loop" diagnosis

capture the ROM bootloader output
# put board in normal boot mode (don't hold BOOT)
# open serial at 115200 (most chips) or 74880 (classic ESP32 ROM is 74880!)
picocom -b 74880 /dev/ttyUSB0
# press EN/RST

# on classic ESP32 you'll see the cryptic ROM line first:
# rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
# configsip: 0, SPIWP:0xee
# clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
# mode:DIO, clock div:2
# load:0x3fff0030,len:1184
# ho 0 tail 12 room 4
# load:0x40078000,len:13260
# load:0x40080400,len:3028
# entry 0x400805e4
# [then second-stage bootloader takes over at 115200]

The ROM speaks at 74880 baud (an artifact of the 26MHz crystal divisor). If the second-stage bootloader never starts, you'll only see ROM output. rst:0x10 means RTC_WDT_RTC_RESET — a watchdog timeout caused the reset. boot:0x13 is SPI fast flash boot, the normal mode. Other boot codes indicate strap pin states. The header lines are dense but they tell you exactly what mode the chip thinks it's in.

Reset reason codes

External flash reflashing (last resort)

If the ESP32 itself is dead or its UART path is locked, but the SPI flash chip is socketed (some boards) or accessible with hot air, you can read/write it directly with any SPI flash programmer.

flashrom on a soic-8 clip
# identify chip first
flashrom --programmer ch341a_spi

# dump existing
flashrom --programmer ch341a_spi -r dump.bin

# write new image (must be padded to flash size)
flashrom --programmer ch341a_spi -w merged_full.bin

# or use a Bus Pirate as the SPI programmer
flashrom --programmer buspirate_spi:dev=/dev/ttyUSB0,spispeed=1M -r dump.bin

Further Rabbit Holes

Things to read and experiment with to keep deepening. Each one leads to better questions.