ESP32-WROOM-32 devkit — 30-pin
The commodity ESP32 board: ESP-WROOM-32 module, USB-serial bridge, LDO, two buttons,
15 pins a side. It is the one that fits a breadboard with a row free, which is why it
outsells the 36- and 38-pin versions.
Nearly every failure on this board comes from a pin that has a second job. Read
reference/board-hardware.md before choosing pins rather than guessing from a tutorial —
a lot of ESP32 tutorials were written for a different board size.
reference/board-hardware.md — the board: header pin map with every pin's alternate
functions, what is not broken out and why that helps, the USB bridge and auto-reset
circuit, power tree, flash partitions — plus a development guide (§10 toolchain,
§11 sdkconfig, §12 flashing and recovery, §13 peripheral cookbook, §14 symptom → cause
→ fix table).
reference/esp32-soc.md — the silicon: pins that do not exist, strapping semantics and
the GPIO_STRAP_REG bit order, ADC/DAC/touch maps and accuracy, IO_MUX vs GPIO Matrix
and the SPI speed rule, power modes, memory map, deep-sleep wake pins.
reference/esp32-family.md — the rest of the family, for "should this be a different
ESP32?" questions: what does and does not port between chips, radio and USB capability
per chip, the RMT generation table (WS2812 under Wi-Fi load), deep-sleep memory and
ULP/LP-core availability, and a chip-selection table.
reference/recipes.md — code that compiles: platformio.ini, sdkconfig.defaults,
ADC1 with calibration, LEDC LED and servo, debounced input, the new I2C master driver,
80 MHz SPI, UART2, Wi-Fi scan and station connect, NVS, deep sleep, RMT WS2812.
template/ — a project that builds clean, in two variants, plus a scaffold script.
See template/README.md.
Confirm the board first
The 30-, 36- and 38-pin ESP32 devkits share silicon but not a header, and the pin map is
what this skill is for. Count the pins on one side:
| Pins per side |
Flash pins on the header |
IO0/D0 pin |
GND pins |
Skill |
| 15 |
no |
no |
2 |
this one |
| 18 |
yes (SD2 SD3 CMD / SD1 SD0 CLK) |
no |
2 |
esp32-wroom-36pin |
| 19 |
yes (D2 D3 CMD / D1 D0 CLK) |
yes |
3 |
esp32-wroom-38pin |
If the count does not match, switch skills. reference/board-hardware.md §1 has the detail.
Orientation
|
|
| Module |
ESP32-WROOM-32 (ESP-WROOM-32), ESP32-D0WDQ6 or D0WD-V3, Xtensa LX6 dual-core @ 240 MHz |
| Memory |
4 MB in-package flash, 520 KB SRAM (~320 KB linkable), 8 KB RTC FAST + 8 KB RTC SLOW. No PSRAM |
| Header |
30 pins, 15 per side. 25 GPIOs, 2× GND, VIN, 3V3, EN |
| USB |
No USB peripheral in the chip. A CH340G/CP2102 bridge on UART0 (GPIO1/GPIO3), with DTR/RTS auto-reset |
| Console |
UART0 @ 115200 only. There is no USB-Serial-JTAG and no debug header |
| LED |
one blue user LED on GPIO2, active high (a strapping pin) |
| Buttons |
BOOT = GPIO0, pressed low, not on the header · EN/RST acts on CHIP_PU, not readable |
| Free pins |
4, 13, 14, 16, 17, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33 |
| Input-only |
34, 35, 36 (VP), 39 (VN) — no output driver, no internal pulls |
| Strapping |
2, 5, 12 (MTDI), 15 (MTDO) — usable, with the caveats in rule 2 |
| Analog |
ADC1 on 32–36, 39 · ADC2 on 0, 2, 4, 12–15, 25–27 · DAC on 25 and 26 |
| Radio |
Wi-Fi b/g/n + Bluetooth 4.2 BR/EDR + BLE, PCB antenna on the module |
| Power |
3V3 out (~600 mA budget) · VIN 5–12 V in, 5 V out. No ORing diode |
| Toolchain |
PlatformIO 6.1.19 + platform-espressif32 7.0.1 + ESP-IDF 6.0.1, board = esp32dev |
Rules that prevent the expensive mistakes
Each of these produces a failure that looks like something else.
CONFIG_ESP_CONSOLE_UART_DEFAULT=y, never ..._USB_SERIAL_JTAG. The original
ESP32 has no USB peripheral at all — every byte you see comes out of UART0 through
a separate bridge chip. Configuration copied from an ESP32-C3/C6/S3 project produces a
firmware that runs perfectly and says nothing, and you debug blind. This is the single
most common cross-chip mistake.
GPIO12 must be LOW at reset. It is MTDI, and high at reset straps VDD_SDIO to
1.8 V while the module's flash is a 3.3 V part. The board then boots intermittently and
the symptom looks like flash corruption, not like a pin problem. A pull-up resistor,
an LED to 3V3, or a peripheral that idles a line high on GPIO12 all do it. It is a fine
pin after boot; add a 10 kΩ pull-down if you must use it.
ADC2 is dead while Wi-Fi is running. The Wi-Fi PHY arbitrates for the same
hardware and wins: adc_oneshot_read() on any ADC2 channel returns ESP_ERR_TIMEOUT
until esp_wifi_stop(). There is no workaround. That leaves ADC1 — GPIO32, 33, 34,
35, 36, 39 — as the entire analog budget of a connected application. Plan the pinout
around it before wiring, not after.
SPI3_HOST on GPIO18/19/23/5, or you get 26.67 MHz. Those four are SPI3's IO_MUX
pads and bypass the GPIO Matrix. Any other pin set — or the same pins on SPI2_HOST —
is matrix-routed, and the driver silently clamps full-duplex transfers to 80 MHz / 3
because of the matrix's 25 ns delay. No error is reported;
spi_device_get_actual_freq() is how you find out.
GPIO34/35/36/39 are input-only and have no internal pull-up or pull-down.
gpio_config() accepts GPIO_PULLUP_ENABLE on them and returns ESP_OK. Nothing
happens. A button on GPIO34 needs a physical 10 kΩ resistor, and a floating one reads
as noise rather than as a stable level.
A reset the moment Wi-Fi starts is the power supply, not your code. The TX burst
pulls ~300 mA; the datasheet asks for a 500 mA source. A laptop USB-2 port, a thin
cable or a lying hub all produce the same signature — everything works until the first
packet. esp_reset_reason() returns ESP_RST_BROWNOUT; say so rather than reading the
stack trace.
Never power VIN and USB at the same time. There is no ORing diode. With USB
connected, VIN is an output at ~5 V and a second supply back-feeds the host.
UART1's default pins are GPIO9 and GPIO10 — the in-package flash bus. Using UART1
without uart_set_pin() first hangs the board. Use UART2 on GPIO17/GPIO16 instead,
and note that uart_set_pin() must come before uart_driver_install() — the reverse
order compiles, runs, and leaves the peripheral on its defaults.
Only RTC GPIOs wake the chip from deep sleep: 0, 2, 4, 12–15, 25–27, 32–36, 39.
GPIO5, 16, 17, 18, 19, 21, 22, 23 cannot, however you configure the interrupt. And the
wake pin's pull must be set with rtc_gpio_pullup_en(), not gpio_set_pull_mode() —
the digital pull registers are powered down in sleep.
Deep sleep on this board is 8–20 mA, not 10 µA. The LDO's quiescent draw, the USB
bridge chip and the power LED are all still on. The datasheet's 10 µA is the bare
chip. Never quote it for a devkit.
Do not set CONFIG_SPIRAM=y. A WROOM-32 has no PSRAM; the driver fails to find it
and aborts before app_main(), which reads as a bricked board. That option belongs to
WROVER modules.
CONFIG_ESP32_XTAL_FREQ_40=y. The module's crystal is 40 MHz. The 26 MHz setting
exists for other modules and garbles the console at every baud rate, which reads as
a broken cable.
GPIO0 is not on this header — it is wired only to the BOOT button and the
auto-reset transistor. That is a feature: unlike a 38-pin board, nothing you wire can
accidentally hold the boot strap and drop the board into download mode. Do not look
for a D0 pin; there isn't one.
The internal I2C pull-ups are 45 kΩ. Fine for two devices on a short jumper, not
for a metre of ribbon or 400 kHz. A bus that scans clean at 100 kHz and fails at
400 kHz needs external 4.7 kΩ resistors, not a driver change.
When the task is choosing pins
Work outward from the constraints, in this order:
- Analog first. If Wi-Fi is in the design, every analog input must land on GPIO32,
33, 34, 35, 36 or 39 (rule 3). Four of those six are input-only, which suits sensors.
- Then the fast bus. If anything needs SPI above 26 MHz, GPIO18/19/23/5 are spoken
for (rule 4).
- Then outputs that must be quiet at boot. GPIO2 is driven briefly by the bootloader
and carries the LED; GPIO1 emits the ROM log at 115200 baud. A relay or a MOSFET gate
on either clicks on every reset.
- Everything else goes on 4, 13, 14, 16, 17, 19, 21, 22, 23, 25, 26, 27 — 15 pins,
which is usually plenty, and the reason this board is enough for most projects.
If you run out, the 36- and 38-pin boards do not help: their extra pins are the flash
bus, which is unusable, plus GPIO0 on the 38-pin. The usable GPIO set is identical on all
three. Reach for an I2C GPIO expander instead.
When the task is "the board does not work"
Diagnose in this order — each stage only depends on the ones before it:
- Does the port enumerate? No port ⇒ cable (try a known data cable) or bridge driver.
- Does anything print at 115200? The ROM bootloader's
rst:0x1 (POWERON_RESET)
banner comes out before any of your configuration applies. If that is absent but the
port exists, suspect the cable's data lines or a wedged bridge chip.
- Does it print but say nothing after? Rule 1 — the console is misconfigured, or
MTDO/GPIO15 is strapped low.
- Does it boot-loop? Read
rst:. ESP_RST_BROWNOUT ⇒ rule 6. RTCWDT_RTC_RESET or
invalid header ⇒ esptool.py erase_flash and reflash the minimal variant.
- Does it reach
app_main() and then misbehave? Flash --minimal to establish a
baseline, then add one subsystem at a time. The full variant's report prints the
strapping latches, the reset reason and the heap, which answers most of what is left.
template/src/board_report.c runs steps 3–5 for you and is worth pasting into any project
that is misbehaving.
Starting a new project
Do not hand-assemble one. template/ builds clean; scaffold from it:
~/.claude/skills/esp32-wroom-30pin/template/variants/new-project.sh <target-dir> [--full|--minimal]
cd <target-dir> && pio run
--minimal — LED blink on GPIO2 + console heartbeat. 144,493 B flash, 13,380 B RAM.
Flash this first on a board you have not used before: it touches only the toolchain, the
flashing route, UART0 and one GPIO, and its two outputs fail independently — LED but no
console means the serial side, console but no LED means this board has no LED on GPIO2.
--full (default) — board self-test: chip/reset/strapping report, partition dump, ADC1
with calibration, Wi-Fi scan, LEDC heartbeat, BOOT button to re-run. 784,417 B flash,
37,036 B RAM. The jump is the Wi-Fi stack.
Both build as-is with ESP-IDF 6.0.1 (verified, zero warnings). Nothing is generated and no
paths are embedded, so copying template/ by hand works identically.
template/README.md maps files to subsystems so a --full scaffold can be stripped back.
When the user already has a project, prefer bringing it in line with the template's
platformio.ini, sdkconfig.defaults and include/board.h over rewriting their code.
Arduino (framework = arduino) is a perfectly reasonable choice for this board and every
pin rule above applies unchanged — but the Arduino core's analogRead() hides the
ADC2/Wi-Fi conflict of rule 3 instead of reporting it.
Flashing
pio run -t upload -t monitor
The bridge chip's DTR/RTS drive EN and GPIO0 through the two-transistor auto-reset circuit,
so esptool handles the whole cycle with no buttons. The board appears as
/dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART (macOS), /dev/ttyUSB0 (Linux, needs
dialout membership), or a COM port (Windows, WCH or Silicon Labs driver).
When it fails with Wrong boot mode detected or No serial data received, the manual
sequence is: hold BOOT → tap EN → keep BOOT a second longer → release BOOT → upload.
Some clones need BOOT held for the whole upload. If 921600 baud is unreliable, drop
upload_speed to 460800.
Bad firmware cannot brick this board. The ROM bootloader is in mask ROM and always
answers that sequence:
esptool.py --chip esp32 -p <port> erase_flash # ~10 s for 4 MB
There is no debug header and no USB-JTAG. External JTAG means wiring a probe to
GPIO12/13/14/15 — and a probe that idles MTDI (GPIO12) high stops the board booting
(rule 2). In practice you debug this board over UART0.
Reporting
Say what is verified and what is derived.
Verified on this machine: both template variants build clean with PlatformIO 6.1.19 /
platform-espressif32 7.0.1 / ESP-IDF 6.0.1, zero warnings, at the flash and RAM figures
quoted above. Every recipe in reference/recipes.md was compiled in the same project.
Taken from primary documents: everything in reference/esp32-soc.md (ESP32 Series
Datasheet v4.3, ESP32-WROOM-32 Datasheet v3.1, ESP32 TRM v5.8), and the 26.67 MHz SPI
figure, which is computed from _GPIO_MATRIX_DELAY_NS in the IDF HAL.
Not verified on hardware: none of this was run on a physical board in this session. The
board-level details that vary by vendor — the user LED's pin and polarity, which bridge
chip is fitted, whether the auto-reset transistors are present — are stated for the
DOIT/CH340 mainstream and should be confirmed with the --minimal variant on the user's
actual board. Say so rather than presenting them as certain.
1---2name: esp32-wroom-30pin3description: ESP32-WROOM-32 devkit — 30-pin4---56# ESP32-WROOM-32 devkit — 30-pin78The commodity ESP32 board: `ESP-WROOM-32` module, USB-serial bridge, LDO, two buttons,915 pins a side. It is the one that fits a breadboard with a row free, which is why it10outsells the 36- and 38-pin versions.1112Nearly every failure on this board comes from a pin that has a second job. Read13`reference/board-hardware.md` before choosing pins rather than guessing from a tutorial —14a lot of ESP32 tutorials were written for a different board size.1516- `reference/board-hardware.md` — the board: header pin map with every pin's alternate17 functions, what is *not* broken out and why that helps, the USB bridge and auto-reset18 circuit, power tree, flash partitions — **plus** a development guide (§10 toolchain,19 §11 sdkconfig, §12 flashing and recovery, §13 peripheral cookbook, §14 symptom → cause20 → fix table).21- `reference/esp32-soc.md` — the silicon: pins that do not exist, strapping semantics and22 the `GPIO_STRAP_REG` bit order, ADC/DAC/touch maps and accuracy, IO_MUX vs GPIO Matrix23 and the SPI speed rule, power modes, memory map, deep-sleep wake pins.24- `reference/esp32-family.md` — the rest of the family, for "should this be a different25 ESP32?" questions: what does and does not port between chips, radio and USB capability26 per chip, the RMT generation table (WS2812 under Wi-Fi load), deep-sleep memory and27 ULP/LP-core availability, and a chip-selection table.28- `reference/recipes.md` — code that compiles: `platformio.ini`, `sdkconfig.defaults`,29 ADC1 with calibration, LEDC LED and servo, debounced input, the new I2C master driver,30 80 MHz SPI, UART2, Wi-Fi scan and station connect, NVS, deep sleep, RMT WS2812.31- `template/` — a **project that builds clean**, in two variants, plus a scaffold script.32 See `template/README.md`.3334## Confirm the board first3536The 30-, 36- and 38-pin ESP32 devkits share silicon but not a header, and the pin map is37what this skill is for. Count the pins on one side:3839| Pins per side | Flash pins on the header | `IO0`/`D0` pin | GND pins | Skill |40|---|---|---|---|---|41| **15** | **no** | **no** | **2** | **this one** |42| 18 | yes (`SD2 SD3 CMD` / `SD1 SD0 CLK`) | no | 2 | `esp32-wroom-36pin` |43| 19 | yes (`D2 D3 CMD` / `D1 D0 CLK`) | yes | 3 | `esp32-wroom-38pin` |4445If the count does not match, switch skills. `reference/board-hardware.md` §1 has the detail.4647## Orientation4849| | |50|---|---|51| Module | ESP32-WROOM-32 (ESP-WROOM-32), ESP32-D0WDQ6 or D0WD-V3, **Xtensa LX6 dual-core** @ 240 MHz |52| Memory | 4 MB in-package flash, 520 KB SRAM (**~320 KB linkable**), 8 KB RTC FAST + 8 KB RTC SLOW. **No PSRAM** |53| Header | 30 pins, 15 per side. **25 GPIOs**, 2× GND, VIN, 3V3, EN |54| USB | **No USB peripheral in the chip.** A CH340G/CP2102 bridge on UART0 (GPIO1/GPIO3), with DTR/RTS auto-reset |55| Console | UART0 @ 115200 only. There is no USB-Serial-JTAG and no debug header |56| LED | one blue user LED on **GPIO2**, active **high** (a strapping pin) |57| Buttons | **BOOT** = GPIO0, pressed low, **not on the header** · **EN/RST** acts on CHIP_PU, not readable |58| Free pins | 4, 13, 14, 16, 17, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33 |59| Input-only | 34, 35, 36 (VP), 39 (VN) — no output driver, **no internal pulls** |60| Strapping | 2, 5, 12 (MTDI), 15 (MTDO) — usable, with the caveats in rule 2 |61| Analog | ADC1 on 32–36, 39 · ADC2 on 0, 2, 4, 12–15, 25–27 · DAC on **25 and 26** |62| Radio | Wi-Fi b/g/n + Bluetooth 4.2 BR/EDR + BLE, PCB antenna on the module |63| Power | 3V3 out (~600 mA budget) · VIN 5–12 V in, 5 V out. No ORing diode |64| Toolchain | PlatformIO 6.1.19 + `platform-espressif32` 7.0.1 + ESP-IDF 6.0.1, `board = esp32dev` |6566## Rules that prevent the expensive mistakes6768Each of these produces a failure that looks like something else.69701. **`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`, never `..._USB_SERIAL_JTAG`.** The original71 ESP32 has **no USB peripheral at all** — every byte you see comes out of UART0 through72 a separate bridge chip. Configuration copied from an ESP32-C3/C6/S3 project produces a73 firmware that runs perfectly and says nothing, and you debug blind. This is the single74 most common cross-chip mistake.75762. **GPIO12 must be LOW at reset.** It is MTDI, and high at reset straps VDD_SDIO to77 1.8 V while the module's flash is a 3.3 V part. The board then boots intermittently and78 the symptom looks like *flash corruption*, not like a pin problem. A pull-up resistor,79 an LED to 3V3, or a peripheral that idles a line high on GPIO12 all do it. It is a fine80 pin after boot; add a 10 kΩ pull-down if you must use it.81823. **ADC2 is dead while Wi-Fi is running.** The Wi-Fi PHY arbitrates for the same83 hardware and wins: `adc_oneshot_read()` on any ADC2 channel returns `ESP_ERR_TIMEOUT`84 until `esp_wifi_stop()`. There is no workaround. That leaves **ADC1 — GPIO32, 33, 34,85 35, 36, 39** — as the entire analog budget of a connected application. Plan the pinout86 around it before wiring, not after.87884. **`SPI3_HOST` on GPIO18/19/23/5, or you get 26.67 MHz.** Those four are SPI3's IO_MUX89 pads and bypass the GPIO Matrix. Any other pin set — or the same pins on `SPI2_HOST` —90 is matrix-routed, and the driver silently clamps full-duplex transfers to 80 MHz / 391 because of the matrix's 25 ns delay. No error is reported;92 `spi_device_get_actual_freq()` is how you find out.93945. **GPIO34/35/36/39 are input-only and have no internal pull-up or pull-down.**95 `gpio_config()` accepts `GPIO_PULLUP_ENABLE` on them and returns `ESP_OK`. Nothing96 happens. A button on GPIO34 needs a physical 10 kΩ resistor, and a floating one reads97 as noise rather than as a stable level.98996. **A reset the moment Wi-Fi starts is the power supply, not your code.** The TX burst100 pulls ~300 mA; the datasheet asks for a 500 mA source. A laptop USB-2 port, a thin101 cable or a lying hub all produce the same signature — everything works until the first102 packet. `esp_reset_reason()` returns `ESP_RST_BROWNOUT`; say so rather than reading the103 stack trace.1041057. **Never power VIN and USB at the same time.** There is no ORing diode. With USB106 connected, VIN is an *output* at ~5 V and a second supply back-feeds the host.1071088. **UART1's default pins are GPIO9 and GPIO10 — the in-package flash bus.** Using UART1109 without `uart_set_pin()` first hangs the board. Use **UART2 on GPIO17/GPIO16** instead,110 and note that `uart_set_pin()` must come *before* `uart_driver_install()` — the reverse111 order compiles, runs, and leaves the peripheral on its defaults.1121139. **Only RTC GPIOs wake the chip from deep sleep**: 0, 2, 4, 12–15, 25–27, 32–36, 39.114 GPIO5, 16, 17, 18, 19, 21, 22, 23 cannot, however you configure the interrupt. And the115 wake pin's pull must be set with `rtc_gpio_pullup_en()`, not `gpio_set_pull_mode()` —116 the digital pull registers are powered down in sleep.11711810. **Deep sleep on this board is 8–20 mA, not 10 µA.** The LDO's quiescent draw, the USB119 bridge chip and the power LED are all still on. The datasheet's 10 µA is the bare120 chip. Never quote it for a devkit.12112211. **Do not set `CONFIG_SPIRAM=y`.** A WROOM-32 has no PSRAM; the driver fails to find it123 and aborts before `app_main()`, which reads as a bricked board. That option belongs to124 WROVER modules.12512612. **`CONFIG_ESP32_XTAL_FREQ_40=y`.** The module's crystal is 40 MHz. The 26 MHz setting127 exists for other modules and garbles the console at *every* baud rate, which reads as128 a broken cable.12913013. **GPIO0 is not on this header** — it is wired only to the BOOT button and the131 auto-reset transistor. That is a feature: unlike a 38-pin board, nothing you wire can132 accidentally hold the boot strap and drop the board into download mode. Do not look133 for a `D0` pin; there isn't one.13413514. **The internal I2C pull-ups are 45 kΩ.** Fine for two devices on a short jumper, not136 for a metre of ribbon or 400 kHz. A bus that scans clean at 100 kHz and fails at137 400 kHz needs external 4.7 kΩ resistors, not a driver change.138139## When the task is choosing pins140141Work outward from the constraints, in this order:1421431. **Analog first.** If Wi-Fi is in the design, every analog input must land on GPIO32,144 33, 34, 35, 36 or 39 (rule 3). Four of those six are input-only, which suits sensors.1452. **Then the fast bus.** If anything needs SPI above 26 MHz, GPIO18/19/23/5 are spoken146 for (rule 4).1473. **Then outputs that must be quiet at boot.** GPIO2 is driven briefly by the bootloader148 and carries the LED; GPIO1 emits the ROM log at 115200 baud. A relay or a MOSFET gate149 on either clicks on every reset.1504. **Everything else** goes on 4, 13, 14, 16, 17, 19, 21, 22, 23, 25, 26, 27 — 15 pins,151 which is usually plenty, and the reason this board is enough for most projects.152153If you run out, the 36- and 38-pin boards do **not** help: their extra pins are the flash154bus, which is unusable, plus GPIO0 on the 38-pin. The usable GPIO set is identical on all155three. Reach for an I2C GPIO expander instead.156157## When the task is "the board does not work"158159Diagnose in this order — each stage only depends on the ones before it:1601611. **Does the port enumerate?** No port ⇒ cable (try a known data cable) or bridge driver.1622. **Does anything print at 115200?** The ROM bootloader's `rst:0x1 (POWERON_RESET)`163 banner comes out before any of your configuration applies. If that is absent but the164 port exists, suspect the cable's data lines or a wedged bridge chip.1653. **Does it print but say nothing after?** Rule 1 — the console is misconfigured, or166 MTDO/GPIO15 is strapped low.1674. **Does it boot-loop?** Read `rst:`. `ESP_RST_BROWNOUT` ⇒ rule 6. `RTCWDT_RTC_RESET` or168 `invalid header` ⇒ `esptool.py erase_flash` and reflash the minimal variant.1695. **Does it reach `app_main()` and then misbehave?** Flash `--minimal` to establish a170 baseline, then add one subsystem at a time. The full variant's report prints the171 strapping latches, the reset reason and the heap, which answers most of what is left.172173`template/src/board_report.c` runs steps 3–5 for you and is worth pasting into any project174that is misbehaving.175176## Starting a new project177178Do not hand-assemble one. `template/` builds clean; scaffold from it:179180```sh181~/.claude/skills/esp32-wroom-30pin/template/variants/new-project.sh <target-dir> [--full|--minimal]182cd <target-dir> && pio run183```184185- `--minimal` — LED blink on GPIO2 + console heartbeat. **144,493 B flash, 13,380 B RAM.**186 Flash this first on a board you have not used before: it touches only the toolchain, the187 flashing route, UART0 and one GPIO, and its two outputs fail independently — LED but no188 console means the serial side, console but no LED means this board has no LED on GPIO2.189- `--full` (default) — board self-test: chip/reset/strapping report, partition dump, ADC1190 with calibration, Wi-Fi scan, LEDC heartbeat, BOOT button to re-run. **784,417 B flash,191 37,036 B RAM.** The jump is the Wi-Fi stack.192193Both build as-is with ESP-IDF 6.0.1 (verified, zero warnings). Nothing is generated and no194paths are embedded, so copying `template/` by hand works identically.195`template/README.md` maps files to subsystems so a `--full` scaffold can be stripped back.196197When the user already has a project, prefer bringing it in line with the template's198`platformio.ini`, `sdkconfig.defaults` and `include/board.h` over rewriting their code.199200Arduino (`framework = arduino`) is a perfectly reasonable choice for this board and every201pin rule above applies unchanged — but the Arduino core's `analogRead()` hides the202ADC2/Wi-Fi conflict of rule 3 instead of reporting it.203204## Flashing205206```sh207pio run -t upload -t monitor208```209210The bridge chip's DTR/RTS drive EN and GPIO0 through the two-transistor auto-reset circuit,211so esptool handles the whole cycle with no buttons. The board appears as212`/dev/cu.usbserial-*` or `/dev/cu.SLAB_USBtoUART` (macOS), `/dev/ttyUSB0` (Linux, needs213`dialout` membership), or a `COM` port (Windows, WCH or Silicon Labs driver).214215When it fails with `Wrong boot mode detected` or `No serial data received`, the manual216sequence is: **hold BOOT → tap EN → keep BOOT a second longer → release BOOT → upload.**217Some clones need BOOT held for the whole upload. If 921600 baud is unreliable, drop218`upload_speed` to 460800.219220**Bad firmware cannot brick this board.** The ROM bootloader is in mask ROM and always221answers that sequence:222223```sh224esptool.py --chip esp32 -p <port> erase_flash # ~10 s for 4 MB225```226227There is no debug header and no USB-JTAG. External JTAG means wiring a probe to228GPIO12/13/14/15 — and a probe that idles MTDI (GPIO12) high stops the board booting229(rule 2). In practice you debug this board over UART0.230231## Reporting232233Say what is verified and what is derived.234235**Verified on this machine:** both template variants build clean with PlatformIO 6.1.19 /236platform-espressif32 7.0.1 / ESP-IDF 6.0.1, zero warnings, at the flash and RAM figures237quoted above. Every recipe in `reference/recipes.md` was compiled in the same project.238239**Taken from primary documents:** everything in `reference/esp32-soc.md` (ESP32 Series240Datasheet v4.3, ESP32-WROOM-32 Datasheet v3.1, ESP32 TRM v5.8), and the 26.67 MHz SPI241figure, which is computed from `_GPIO_MATRIX_DELAY_NS` in the IDF HAL.242243**Not verified on hardware:** none of this was run on a physical board in this session. The244board-level details that vary by vendor — the user LED's pin and polarity, which bridge245chip is fitted, whether the auto-reset transistors are present — are stated for the246DOIT/CH340 mainstream and should be confirmed with the `--minimal` variant on the user's247actual board. Say so rather than presenting them as certain.