Esp8266 Nodemcu 30pin

---
name: esp8266-nodemcu-30pin
description: Firmware development for the 30-pin NodeMCU ESP8266 devkit — NodeMCU DevKit V1.0 / Amica (CP2102) and LoLin NodeMCU V3 (CH340G), built on the Ai-Thinker ESP-12E or ESP-12F module (ESP8266EX, 4 MB flash), with PlatformIO and the Arduino ESP8266 core (`board = nodemcuv2`). Use when working on a NodeMCU, ESP-12E, ESP-12F or ESP8266 devkit: project setup, platformio.ini, the D0-D10 vs GPIO numbering, which pins are safe and which break the boot, GPIO15/GPIO0/GPIO2 strapping, the A0 divider and 1 V ADC, software I2C and software PWM, analogWrite range, LittleFS and flash layouts, OTA, deep sleep and the missing GPIO16-to-RST link, Wi-Fi, heap exhaustion, watchdog and Soft WDT resets, exception decoding, flashing over CP2102/CH340, or debugging why the board does not boot, prints garbage, or reboots by itself.
---

# NodeMCU ESP8266 devkit — 30-pin

The board that made the ESP8266 usable: an Ai-Thinker ESP-12E/F module, a USB-UART
bridge, an LDO, two buttons, 15 pins a side. Everything hard about it is a pin with a
second job, a peripheral that is software rather than silicon, or a number that means
something different than it looks like.

Read `reference/board-hardware.md` before choosing pins. Most ESP8266 tutorials are
written for core 2.x and for a different board; several of their defaults are now wrong.

- `reference/board-hardware.md` — the board: full header map with D-number ↔ GPIO
  translation, the strapping resistors and their values, the two LEDs, the A0 divider,
  the auto-program circuit and its truth table, the power tree — **plus** a development
  guide (§9 toolchain and flash layouts, §10 flashing and recovery, §11 peripheral
  cookbook, §12 symptom → cause → fix table).
- `reference/esp8266-soc.md` — the silicon: the 17 GPIOs and which six are the flash
  bus, memory map and why a sketch cannot exceed ~1 MB, clocks, the ADC's two mutually
  exclusive modes, UART/SPI/HSPI/I2S pin tables, PWM as a timer service, sleep modes and
  their real currents.
- `reference/recipes.md` — code that compiles: `platformio.ini` variants, digital and
  analog IO, software I2C and its scanner, HSPI, LittleFS, Wi-Fi station with reconnect,
  ArduinoOTA, deep sleep with RTC memory, Ticker, WS2812 over I2S, and the watchdog and
  exception-decoder recipes.
- `template/` — a **project that builds clean and was run on hardware**, in two
  variants, plus a scaffold script. See `template/README.md`.

## Confirm the board first

All 30-pin NodeMCU boards share the module, the pin map and every rule below. Two things
differ, and both bite:

| | DevKit V1.0 / Amica ("V2") | LoLin NodeMCU V3 |
|---|---|---|
| Bridge | CP2102 (Silicon Labs VCP driver) | CH340G (WCH driver) |
| Size | 48 × 26 mm — fits a breadboard with a row free | 58 × 31 mm — **covers both rails**, needs two breadboards |
| Two pads next to A0 | `RSV`, `RSV` — not connected | `VU` (USB 5 V, pre-LDO) and `GND` |
| Port name | `cu.SLAB_USBtoUART` / `cu.usbserial-0001` | `cu.usbserial-*`, VID 0x1A86 PID 0x7523 |

Anything else labelled "NodeMCU 30-pin" — CH340 clones of the V1.0 layout are common — is
a V1.0 electrically. If the user needs to know which they have, `pio device list` names
the bridge chip.

## Orientation

| | |
|---|---|
| Module | ESP-12E or ESP-12F (Ai-Thinker), ESP8266EX, **Tensilica L106 32-bit, single core** @ 80 MHz (160 MHz optional) |
| Memory | 4 MB flash on-module, ~80 KB usable SRAM. **~50 KB free heap in a bare sketch** — verified. No PSRAM, no data cache to speak of |
| Program space | **1,044,464 B** with the default `4m1m` layout + 1 MB LittleFS. A sketch cannot exceed ~1 MB whatever the flash size |
| Crystal | **26 MHz** (verified by esptool). This is why the ROM log is 74880 baud |
| Header | 30 pins, 15 per side. **9 usable GPIOs**, 6 more are the flash bus and must not be touched |
| USB | No USB peripheral in the chip. CP2102 or CH340G bridge on UART0 (GPIO1/GPIO3) with DTR+RTS auto-reset |
| Console | UART0 @ 115200 for your sketch; **74880 for the ROM bootloader**. No JTAG, no debug header |
| LEDs | GPIO2 on the module (`LED_BUILTIN`) and GPIO16 on the PCB (`LED_BUILTIN_AUX`), **both active LOW** |
| Buttons | **FLASH** = GPIO0, pressed low · **RST** acts on nRST, not readable |
| Safe pins | D1 (GPIO5), D2 (GPIO4), D5 (GPIO14), D6 (GPIO12), D7 (GPIO13) |
| Usable with care | D3 (GPIO0), D4 (GPIO2), D8 (GPIO15) — strapping pins, rule 3 · D0 (GPIO16) — rule 4 |
| Never use | SD0–SD3, CLK, CMD = GPIO6–11, the SPI flash bus |
| Analog | one input, A0, 10-bit. Header pin 0–3.2 V through a 220k/100k divider; the chip pad behind it is 0–1.0 V |
| Radio | Wi-Fi b/g/n 2.4 GHz only. **No Bluetooth** — that is the ESP32 |
| Power | 3V3 out (NCP1117, 800 mA) · VIN is a **5 V** input in practice, rule 13 |
| Toolchain | PlatformIO + `platform-espressif8266` 4.2.1 + Arduino core 3.1.2, `board = nodemcuv2` |

## Rules that prevent the expensive mistakes

Each of these produces a failure that looks like something else.

1. **The D-numbers are not GPIO numbers, and they are not in order.**
   `D1 = GPIO5, D2 = GPIO4, D3 = GPIO0, D4 = GPIO2, D5 = GPIO14, D6 = GPIO12,
   D7 = GPIO13, D8 = GPIO15, D0 = GPIO16.` Note D1/D2 are *swapped* relative to
   intuition. `digitalWrite(2, …)` and `digitalWrite(D2, …)` are different pins and both
   compile. Pick one scheme per project and never mix them; when reading a user's code,
   check which one they meant before diagnosing anything else.

2. **The ROM boot log is 74880 baud, not 115200.** The module's crystal is 26 MHz and the
   ROM derives its baud from it: 115200 × 26/40 = 74880. At 115200 you see a burst of
   garbage before your first line and reach for a different cable. That garbage is
   `ets Jan 8 2013,rst cause:N,boot mode:(M,N)` — the one line that explains a boot loop.
   `pio device monitor -b 74880` reads it. (Verified live: readable at 74880, garbage at
   115200, and vice versa for the sketch's own output.)

3. **GPIO15 must be LOW at reset, GPIO0 and GPIO2 HIGH.** The board fits 12 kΩ resistors
   to guarantee it (pull-down on GPIO15, pull-ups on GPIO0/GPIO2 — schematic sheet 2).
   Anything you wire that fights them stops the chip booting **before any code or any
   serial output**, so the board reads as dead or bricked:
   - a pull-up, an LED to 3V3, or an SPI slave whose CS idles high on **D8/GPIO15**
   - a peripheral holding **D3/GPIO0** low → the chip sits in flash download mode instead
   - anything pulling **D4/GPIO2** low
   A board that does nothing at all, with no serial at either baud, is nearly always this
   and not a dead chip. Unplug everything from D3/D4/D8 and retry before anything else.

4. **GPIO16 (D0) is not a GPIO like the others.** It is XPD_DCDC, on the RTC domain, with
   its own hardware path. No interrupt, no `analogWrite`, no I2C, no OneWire, no Servo,
   no `attachInterrupt` — all of those compile and silently never fire. Its only pull is
   a pull-**down**: `pinMode(16, INPUT_PULLDOWN_16)`; `INPUT_PULLUP` on pin 16 compiles
   and does nothing. `digitalRead`/`digitalWrite` only.

5. **`ESP.deepSleep()` never wakes on a stock NodeMCU.** Waking needs GPIO16 wired to
   RST, and the 0 Ω link for it (R10 on the schematic, marked `0(NC)`; the instruction
   sheet calls it the R3 position) is **not fitted from the factory** — verified on
   hardware here by driving GPIO16 low and watching the chip not reset. The board goes to
   sleep and stays there, which reads as a crash or a brick. Solder the link, or run a
   jumper from D0 to RST. After that GPIO16 is unusable for anything else, and every
   upload needs the jumper off (RST is held).
   `template/src/main.cpp` tests for the link and reports it; use that before writing
   sleep code.

6. **`analogWrite()` range defaults to 255 in core 3.x, not 1023.** It changed from 2.x
   and nothing warns you. Tutorial code that ramps `analogWrite(pin, 0..1023)` sits at
   full brightness for three quarters of its range. Call `analogWriteRange(1023)`
   explicitly, or write 0–255. (`core_esp8266_wiring_pwm.cpp:29`.)

7. **PWM and I2C are software, not peripherals.** PWM is generated from a timer ISR:
   `analogWriteFreq()` clamps to 100 Hz–60 kHz, every additional PWM pin costs interrupt
   time, and Wi-Fi activity puts visible jitter on the output that no amount of tuning
   removes. `Wire` is bit-banged for the same reason. If a project needs clean PWM —
   servos, motor control, LED dimming that must not flicker — say so early: this board is
   the wrong choice, or the PWM belongs on an external driver.

8. **The loop must return.** There is no preemption; the SDK runs the Wi-Fi and TCP stack
   between calls to `loop()`. Blocking for more than ~3 s trips the software watchdog
   (`Soft WDT reset`), ~8 s the hardware one (`wdt reset`). `delay()` and `yield()` feed
   it — a bare `while (!flag) {}` does not, and neither does a long `for` loop over
   flash. A board that reboots every few seconds while "doing nothing wrong" is this.

9. **~50 KB of heap is the whole budget** (verified: 50,408 B free in the full template,
   52,168 B in a blink). One TLS connection costs 16–24 KB of it, so HTTPS plus a web
   server plus a JSON buffer does not fit. `String` concatenation fragments the heap:
   watch `ESP.getMaxFreeBlockSize()`, not `ESP.getFreeHeap()` — allocations fail on the
   largest block long before free memory runs out.

10. **A sketch cannot exceed ~1 MB, whatever the flash size.** `board = nodemcuv2`
    defaults to `eagle.flash.4m1m.ld`: 1,044,464 B of program space and 1 MB of
    filesystem. The ceiling is the flash cache mapping window, not the 4 MB part.
    Changing to `4m2m` or `4m3m` buys filesystem, never sketch. And OTA needs the new
    image to fit *alongside* the running one, so a 600 KB sketch cannot OTA-update itself.

11. **Use LittleFS; SPIFFS is deprecated in core 3.x** and its symbols are marked
    `__attribute__((deprecated))`. Set `board_build.filesystem = littlefs`. A project that
    mounts SPIFFS on a filesystem uploaded as LittleFS fails at `begin()` with no
    explanation.

12. **A0 is not the chip's ADC pin.** The header pin goes through a 220 kΩ / 100 kΩ 1 %
    divider (schematic sheet 7), so it takes 0–3.2 V while the ESP8266's TOUT pad behind
    it takes 0–1.0 V and is destroyed above ~1.1 V. Two consequences: wiring a sensor
    directly to a bare ESP-12E/F ADC pad using NodeMCU code overvolts it, and the divider
    presents ~320 kΩ, so a high-impedance source reads low. Also `ADC_MODE(ADC_VCC)`
    repurposes the ADC to measure the 3V3 rail — after that `analogRead(A0)` is
    meaningless and the header pin must be left floating.

13. **VIN is a 5 V input, not a 7–12 V one.** The sources disagree and the optimistic one
    is wrong in practice: the schematic's power sheet says "Max Supply Voltage 20 V"
    (the NCP1117's rating), while NodeMCU's own instruction sheet says never exceed 5 V.
    The regulator is a linear SOT-223 part — at 12 V and 200 mA it burns 1.7 W and
    thermally shuts down, which presents as random reboots under Wi-Fi load. Feed VIN 5 V.
    A 1N5819 Schottky sits between USB 5 V and that rail, so VIN and USB together will not
    back-feed the host, but do not rely on it as a design.

14. **GPIOs are 3.3 V and not 5 V tolerant, 12 mA maximum per pin** (ESP8266EX datasheet
    Table 5-1). No 5 V sensor, no 5 V I2C bus, no 5 V shield without a level shifter.
    3V3 on the header is an *output*.

15. **A reset the moment Wi-Fi transmits is the supply, not the code.** The TX burst pulls
    ~500 mA peak (ESP-12F datasheet). A laptop USB-2 port, a thin cable or a hub all give
    the same signature: everything works until the first packet. Check
    `ESP.getResetReason()` before reading a stack trace.

16. **Opening the serial port resets the board.** The two-transistor auto-program circuit
    (schematic sheet 3) decodes DTR *and* RTS, so any terminal that asserts either on open
    restarts the chip and you lose the first lines. Set `monitor_dtr = 0` and
    `monitor_rts = 0` to attach without resetting. Separately: with the board powered from
    a computer and the port *not* open, plugging any other USB device in can reset it —
    a documented NodeMCU quirk, not a fault.

## When the task is choosing pins

There are nine usable GPIOs, and only five of them are free of conditions. Work in this
order:

1. **The five safe pins first**: D1 (GPIO5), D2 (GPIO4), D5 (GPIO14), D6 (GPIO12),
   D7 (GPIO13). Put anything that must be quiet at boot here.
2. **I2C** takes D1 + D2 by default (SCL = GPIO5, SDA = GPIO4) — but I2C is software, so
   any two safe pins work: `Wire.begin(sda, scl)`. Moving it off D1/D2 is free and often
   the right call.
3. **HSPI** is fixed in hardware: SCLK = D5, MISO = D6, MOSI = D7, CS = D8. That consumes
   every remaining safe pin plus a strapping pin. Drive CS from a different pin and leave
   D8 alone if you can; if you cannot, make sure the slave does not pull D8 high at reset
   (rule 3).
4. **Then the conditional pins.** D3 (GPIO0) is fine as a button to GND. D4 (GPIO2) is
   fine as an output that idles high — it already drives the module LED. D8 (GPIO15) is
   fine as an output that idles low.
5. **D0 (GPIO16) last**, and only for a plain input or output (rule 4), and only if you
   are not using deep sleep (rule 5).

If that is not enough: an I2C GPIO expander, or the ESP32, which has three times the
pins, real hardware PWM and I2C, and Bluetooth. Recommend the swap rather than
contorting the pinout — the ESP8266's limits here are structural.

## When the task is "the board does not work"

Each stage depends only on the ones before it:

1. **Does the port enumerate?** No port ⇒ a charge-only cable, or a missing CP2102 /
   CH340 driver. `pio device list` names the chip.
2. **Does anything appear at 74880 baud?** The ROM banner comes out before any of your
   code. Present ⇒ the chip and the flash bus are alive. Absent, with the port there ⇒
   power, or **GPIO15 held high** (rule 3).
3. **Read `rst cause:` from that banner.** `1` power-on, `2` external reset, `4` hardware
   watchdog, `3`/`0` exception or software watchdog. `boot mode:(1,x)` means GPIO0 was low
   — the chip is in download mode and your sketch never ran.
4. **Does it print at 115200 and then reboot?** Read `ESP.getResetReason()`.
   *Soft WDT reset* ⇒ rule 8, something blocks. *Exception (n)* ⇒ enable
   `monitor_filters = esp8266_exception_decoder` and re-read the trace with symbols.
   Random resets only under Wi-Fi ⇒ rule 15, then rule 13.
5. **Does it run but misbehave?** Flash `--minimal` to establish a baseline, then add one
   subsystem at a time. The `--full` variant prints the strapping levels, the flash
   identity, the heap and the GPIO16↔RST verdict, which covers most of what is left.

## Starting a new project

Do not hand-assemble one. `template/` builds clean and was run on hardware:

```sh
~/.claude/skills/esp8266-nodemcu-30pin/template/variants/new-project.sh <target-dir> [--full|--minimal]
cd <target-dir> && pio run
```

- `--minimal` — blink on GPIO2 and GPIO16 plus a serial heartbeat. **267,483 B flash,
  28,292 B RAM.** Flash this first on an unfamiliar board: it touches only the toolchain,
  the upload route, UART0 and two GPIOs, and its outputs fail independently.
- `--full` (default) — board self-test: report, boot-strap read-back, GPIO16↔RST link
  probe, ADC, LittleFS boot counter, Wi-Fi scan, dual-LED heartbeat, FLASH button re-runs
  it. **304,199 B flash, 29,792 B RAM.**

Both build with zero warnings on platform-espressif8266 4.2.1 / Arduino core 3.1.2.
Nothing is generated and no paths are embedded, so copying `template/` by hand works
identically. `template/README.md` maps files to subsystems.

**267 KB for a blink is the floor, not bloat** — the core links the non-OS Wi-Fi SDK into
every sketch. Do not go looking for what to strip.

When the user already has a project, prefer bringing their `platformio.ini` and pin
definitions in line with the template over rewriting their code.

## Flashing

```sh
pio run -t upload -t monitor
```

The bridge drives RST and GPIO0 through the auto-program transistors, so esptool runs the
whole cycle with no buttons. 460800 baud is reliable; 921600 is not on CH340 clones. The
board appears as `/dev/cu.usbserial-*` or `/dev/cu.SLAB_USBtoUART` (macOS),
`/dev/ttyUSB0` (Linux — needs `dialout` membership), or a COM port (Windows).

When it fails with `Failed to connect` or `Wrong boot mode detected`:
**hold FLASH → tap RST → release FLASH → upload.** If auto-reset has stopped working
after an interrupted flash, hold FLASH while plugging the USB cable in; that is the
NodeMCU instruction sheet's own recovery step.

**Bad firmware cannot brick this board.** The ROM bootloader is in mask ROM and always
answers that sequence:

```sh
esptool.py --chip esp8266 -p <port> erase_flash    # ~10 s for 4 MB
```

Erasing also wipes the RF calibration sector; the SDK rewrites it on the next boot, so a
first boot after `erase_flash` may take a second longer and print `rf cal sector: …`.

There is no JTAG and no debug header. `GDBStub` (bundled with the core) gives source-level
debugging over UART0 at the cost of the serial console — that is the whole debug story on
this chip. In practice: `Serial`, the exception decoder, and the `--minimal` baseline.

## Reporting

Say what is verified and what is derived.

**Verified on hardware in this session**, on a 30-pin NodeMCU with a CH340G bridge
(VID 0x1A86 / PID 0x7523), ESP-12E/F module, chip id 0x7107F0, flash id 0x00164068,
4 MB, 26 MHz crystal: both template variants build with zero warnings, upload at 460800
and run; the 74880-baud ROM log and its garbling at 115200; strapping levels
GPIO0 = 1 / GPIO2 = 1 / GPIO15 = 0 after boot; ~50 KB free heap; `deepSleepMax` ≈ 3.2 h;
LittleFS mounts and persists; a Wi-Fi scan returns real APs without browning out; and
**GPIO16 is not tied to RST** (rule 5).

**Taken from primary documents:** ESP8266EX Datasheet v7.1, ESP-12E and ESP-12F
datasheets (Ai-Thinker), the NodeMCU DevKit V1.0 schematic and instruction sheet — the
12 kΩ strapping resistor values, the 220k/100k ADC divider, the LED polarity, the
auto-program truth table, the NCP1117 power tree, and the 500 mA TX peak.

**Not verified here:** which LED the user's board actually lights (the module LED on
GPIO2 is present on every ESP-12E/F; the PCB LED on GPIO16 is a NodeMCU addition and is
absent on bare module breakouts), the LoLin V3 `VU`/`GND` pads, and every current figure
in `reference/esp8266-soc.md` §7. Say so rather than presenting them as measured.