319 lines
14 KiB
Markdown
319 lines
14 KiB
Markdown
# ESP32 GPIO Pin Reference
|
||
|
||
> **类别：reference** | **主题：ESP32 GPIO 引脚完整参考** | **信源：** [Espressif 官方文档](https://docs.espressif.com)
|
||
|
||
## Table of Contents
|
||
|
||
- [ESP32 GPIO Model Overview](#esp32-gpio-model-overview)
|
||
- [Pin Categories Summary](#pin-categories-summary)
|
||
- [Complete GPIO Pin Table](#complete-gpio-pin-table)
|
||
- [Flash and PSRAM Reservations](#flash-and-psram-reservations)
|
||
- [GPIO6-11: SPI Flash (NEVER USE)](#gpio6-11-spi-flash-never-use)
|
||
- [GPIO16-17: PSRAM (WROVER Only)](#gpio16-17-psram-wrover-only)
|
||
- [Protocol Pin Groups](#protocol-pin-groups)
|
||
- [I2C (Conventional Defaults)](#i2c-conventional-defaults)
|
||
- [SPI Buses](#spi-buses)
|
||
- [UARTs](#uarts)
|
||
- [PWM (LEDC)](#pwm-ledc)
|
||
- [1-Wire](#1-wire)
|
||
- [DAC (Digital-to-Analog)](#dac-digital-to-analog)
|
||
- [ADC Channel Mapping](#adc-channel-mapping)
|
||
- [ADC1 (Always Available — Even with WiFi)](#adc1-always-available--even-with-wifi)
|
||
- [ADC2 (UNAVAILABLE When WiFi Active)](#adc2-unavailable-when-wifi-active)
|
||
- [Touch Channel Mapping](#touch-channel-mapping)
|
||
- [RTC GPIO Mapping](#rtc-gpio-mapping)
|
||
- [Variant Comparison Table](#variant-comparison-table)
|
||
- [Key Variant Notes](#key-variant-notes)
|
||
|
||
---
|
||
|
||
## ESP32 GPIO Model Overview
|
||
|
||
The ESP32 GPIO system differs fundamentally from Raspberry Pi:
|
||
|
||
- **GPIO Matrix:** Most peripherals can be routed to any GPIO through the GPIO matrix, providing flexible pin assignment (unlike RPi's fixed ALT functions)
|
||
- **Special Pin Categories:** Certain pins have hardware restrictions — strapping pins affect boot behavior, flash pins are never usable, input-only pins cannot drive outputs
|
||
- **Variable Capabilities:** Not all GPIOs have the same features — ADC, touch sensing, DAC, and RTC wake capabilities vary by pin
|
||
- **Variant Differences:** ESP32 variants (S2, S3, C3, C6) have different GPIO counts, capabilities, and restrictions
|
||
|
||
**Default Reference:** This document uses **ESP32-WROOM-32** as the primary reference module unless otherwise noted.
|
||
|
||
---
|
||
|
||
## Pin Categories Summary
|
||
|
||
- **Freely Usable**：GPIOs=4, 13, 14, 16*, 17*, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33, Count=15, Usage=No restrictions, safe for any purpose
|
||
- **Strapping (use with caution)**：GPIOs=0, 2, 5, 12, 15, Count=5, Usage=Affect boot behavior — safe after boot
|
||
- **Flash Reserved**：GPIOs=6, 7, 8, 9, 10, 11, Count=6, Usage=NEVER use — connected to SPI flash
|
||
- **PSRAM Reserved**：GPIOs=16, 17, Count=2, Usage=Reserved on WROVER, free on WROOM
|
||
- **Input Only**：GPIOs=34, 35, 36, 39, Count=4, Usage=Cannot output, no internal pulls
|
||
- **Not Exposed**：GPIOs=20, 24, 28-31, 37, 38, Count=8, Usage=Not available on WROOM-32 module
|
||
|
||
*GPIO16/17 are usable on WROOM but reserved for PSRAM on WROVER modules.
|
||
|
||
---
|
||
|
||
## Complete GPIO Pin Table
|
||
|
||
Reference for ESP32-WROOM-32 module, GPIOs 0-39:
|
||
|
||
- 0：Strapping=YES (boot mode), Reserved=No, I/O=I/O, ADC=ADC2_CH1, Touch=TOUCH1, RTC=RTC_GPIO11, Notes=LOW=download mode; safe after boot
|
||
- 1：Strapping=No, Reserved=No*, I/O=I/O, Notes=UART0 TX — avoid (USB serial)
|
||
- 2：Strapping=YES (boot mode), Reserved=No, I/O=I/O, ADC=ADC2_CH2, Touch=TOUCH2, RTC=RTC_GPIO12, Notes=Often onboard LED; safe after boot
|
||
- 3：Strapping=No, Reserved=No*, I/O=I/O, Notes=UART0 RX — avoid (USB serial)
|
||
- 4：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH0, Touch=TOUCH0, RTC=RTC_GPIO10, Notes=Clean — commonly used for 1-Wire
|
||
- 5：Strapping=YES (SDIO timing), Reserved=No, I/O=I/O, Notes=Internal pull-up; VSPI CS default
|
||
- 6：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash CLK
|
||
- 7：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D0
|
||
- 8：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D1
|
||
- 9：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D2
|
||
- 10：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash D3
|
||
- 11：Strapping=No, Reserved=FLASH, I/O=I/O, Notes=**NEVER USE** — SPI flash CMD
|
||
- 12：Strapping=**YES (MTDI)**, Reserved=No, I/O=I/O, ADC=ADC2_CH5, Touch=TOUCH5, RTC=RTC_GPIO15, Notes=**DANGER:** flash voltage select — see esp32-specifics.md
|
||
- 13：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH4, Touch=TOUCH4, RTC=RTC_GPIO14, Notes=HSPI MOSI default
|
||
- 14：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH6, Touch=TOUCH6, RTC=RTC_GPIO16, Notes=HSPI CLK default
|
||
- 15：Strapping=YES (MTDO), Reserved=No, I/O=I/O, ADC=ADC2_CH3, Touch=TOUCH3, RTC=RTC_GPIO13, Notes=Debug log control; HSPI CS default
|
||
- 16：Strapping=No, Reserved=PSRAM*, I/O=I/O, Notes=Free on WROOM; reserved on WROVER
|
||
- 17：Strapping=No, Reserved=PSRAM*, I/O=I/O, Notes=Free on WROOM; reserved on WROVER
|
||
- 18：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI CLK default
|
||
- 19：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI MISO default
|
||
- 20：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 21：Strapping=No, Reserved=No, I/O=I/O, Notes=I2C SDA default
|
||
- 22：Strapping=No, Reserved=No, I/O=I/O, Notes=I2C SCL default
|
||
- 23：Strapping=No, Reserved=No, I/O=I/O, Notes=VSPI MOSI default
|
||
- 24：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 25：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH8, RTC=RTC_GPIO6, Notes=DAC1 output
|
||
- 26：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH9, RTC=RTC_GPIO7, Notes=DAC2 output
|
||
- 27：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC2_CH7, Touch=TOUCH7, RTC=RTC_GPIO17, Notes=Clean GPIO
|
||
- 28：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 29：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 30：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 31：Strapping=No, Reserved=Not exposed, I/O=I/O, Notes=Not available on WROOM-32
|
||
- 32：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC1_CH4, Touch=TOUCH9, RTC=RTC_GPIO9, Notes=ADC1 — works with WiFi
|
||
- 33：Strapping=No, Reserved=No, I/O=I/O, ADC=ADC1_CH5, Touch=TOUCH8, RTC=RTC_GPIO8, Notes=ADC1 — works with WiFi
|
||
- 34：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH6, RTC=RTC_GPIO4, Notes=Input only, no internal pulls
|
||
- 35：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH7, RTC=RTC_GPIO5, Notes=Input only, no internal pulls
|
||
- 36：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH0, RTC=RTC_GPIO0, Notes=Input only (SENSOR_VP)
|
||
- 37：Strapping=No, Reserved=Not exposed, I/O=**INPUT**, ADC=ADC1_CH1, RTC=RTC_GPIO1, Notes=Not available on WROOM-32
|
||
- 38：Strapping=No, Reserved=Not exposed, I/O=**INPUT**, ADC=ADC1_CH2, RTC=RTC_GPIO2, Notes=Not available on WROOM-32
|
||
- 39：Strapping=No, Reserved=No, I/O=**INPUT**, ADC=ADC1_CH3, RTC=RTC_GPIO3, Notes=Input only (SENSOR_VN)
|
||
|
||
---
|
||
|
||
## Flash and PSRAM Reservations
|
||
|
||
### GPIO6-11: SPI Flash (NEVER USE)
|
||
|
||
These pins are hardwired to the SPI flash chip on all ESP32 modules:
|
||
|
||
- GPIO6：Flash Function=SPICLK, Result if Used=Chip crash/hang
|
||
- GPIO7：Flash Function=SPIQ (D0), Result if Used=Chip crash/hang
|
||
- GPIO8：Flash Function=SPID (D1), Result if Used=Chip crash/hang
|
||
- GPIO9：Flash Function=SPIHD (D2), Result if Used=Chip crash/hang
|
||
- GPIO10：Flash Function=SPIWP (D3), Result if Used=Chip crash/hang
|
||
- GPIO11：Flash Function=SPICS0 (CMD), Result if Used=Chip crash/hang
|
||
|
||
**Rule:** Never assign GPIO6-11 for any purpose. Attempting to use them will crash the chip immediately.
|
||
|
||
### GPIO16-17: PSRAM (WROVER Only)
|
||
|
||
- WROOM-32：GPIO16=Usable, GPIO17=Usable, Reason=No PSRAM on module
|
||
- WROVER：GPIO16=Reserved, GPIO17=Reserved, Reason=Connected to PSRAM
|
||
- WROVER-B：GPIO16=Reserved, GPIO17=Reserved, Reason=Connected to PSRAM
|
||
- WROOM-32E：GPIO16=Usable, GPIO17=Usable, Reason=No PSRAM on module
|
||
|
||
**Rule:** Always check module type. If using WROVER, avoid GPIO16/17.
|
||
|
||
---
|
||
|
||
## Protocol Pin Groups
|
||
|
||
### I2C (Conventional Defaults)
|
||
|
||
Unlike Raspberry Pi, ESP32 I2C can use any GPIO via the GPIO matrix:
|
||
|
||
- SDA：Default GPIO=GPIO21, Notes=Convention only — any GPIO works
|
||
- SCL：Default GPIO=GPIO22, Notes=Convention only — any GPIO works
|
||
|
||
**Usage:**
|
||
```cpp
|
||
// Arduino
|
||
Wire.begin(21, 22); // SDA, SCL
|
||
|
||
// ESP-IDF
|
||
i2c_config_t conf = {
|
||
.sda_io_num = 21,
|
||
.scl_io_num = 22,
|
||
// ...
|
||
};
|
||
```
|
||
|
||
**Note:** Do not use input-only pins (34-39) for I2C — they cannot drive the bus.
|
||
|
||
### SPI Buses
|
||
|
||
ESP32 has two user-accessible SPI buses:
|
||
|
||
**VSPI (SPI3) — Recommended:**
|
||
|
||
- MOSI：GPIO=GPIO23
|
||
- MISO：GPIO=GPIO19
|
||
- SCLK：GPIO=GPIO18
|
||
- CS：GPIO=GPIO5, Notes=Strapping pin — safe after boot
|
||
|
||
**HSPI (SPI2) — Use with caution:**
|
||
|
||
- MOSI：GPIO=GPIO13
|
||
- MISO：GPIO=GPIO12, Notes=**DANGER:** Strapping pin — see esp32-specifics.md
|
||
- SCLK：GPIO=GPIO14
|
||
- CS：GPIO=GPIO15, Notes=Strapping pin — safe after boot
|
||
|
||
**Warning:** HSPI uses GPIO12 which is a dangerous strapping pin. Prefer VSPI unless you specifically need both SPI buses.
|
||
|
||
### UARTs
|
||
|
||
- UART0：TX=GPIO1, RX=GPIO3, Notes=USB serial — avoid unless needed
|
||
- UART1：TX=Any, RX=Any, Notes=Fully remappable via GPIO matrix
|
||
- UART2：TX=Any, RX=Any, Notes=Fully remappable via GPIO matrix
|
||
|
||
**Common UART1/UART2 assignments:**
|
||
- UART1: GPIO4 (TX), GPIO5 (RX)
|
||
- UART2: GPIO16 (TX), GPIO17 (RX) — if not WROVER
|
||
|
||
### PWM (LEDC)
|
||
|
||
ESP32 PWM uses the LEDC peripheral, which can output to any GPIO:
|
||
|
||
- **Channels:** 16 (8 high-speed, 8 low-speed)
|
||
- **Resolution:** 1-16 bits
|
||
- **Frequency:** Up to 40MHz (hardware dependent on duty resolution)
|
||
- **Any output-capable GPIO works** — no fixed PWM pins like RPi
|
||
|
||
**Rule:** Cannot use input-only pins (34-39) for PWM output.
|
||
|
||
### 1-Wire
|
||
|
||
- **Common Pin:** GPIO4 (by convention)
|
||
- **Flexibility:** Any GPIO with output capability
|
||
- **Pull-up:** Requires 4.7kΩ external pull-up to 3.3V
|
||
|
||
### DAC (Digital-to-Analog)
|
||
|
||
- DAC1：GPIO=GPIO25, Notes=8-bit resolution
|
||
- DAC2：GPIO=GPIO26, Notes=8-bit resolution
|
||
|
||
**Note:** DAC is only available on original ESP32 and ESP32-S2. Not available on S3, C3, or C6.
|
||
|
||
---
|
||
|
||
## ADC Channel Mapping
|
||
|
||
### ADC1 (Always Available — Even with WiFi)
|
||
|
||
- ADC1_CH0：GPIO=GPIO36, Notes=Input only (SENSOR_VP)
|
||
- ADC1_CH1：GPIO=GPIO37, Notes=Not on WROOM-32
|
||
- ADC1_CH2：GPIO=GPIO38, Notes=Not on WROOM-32
|
||
- ADC1_CH3：GPIO=GPIO39, Notes=Input only (SENSOR_VN)
|
||
- ADC1_CH4：GPIO=GPIO32, Notes=Full I/O
|
||
- ADC1_CH5：GPIO=GPIO33, Notes=Full I/O
|
||
- ADC1_CH6：GPIO=GPIO34, Notes=Input only
|
||
- ADC1_CH7：GPIO=GPIO35, Notes=Input only
|
||
|
||
**Design Rule:** Use ADC1 channels for analog inputs in WiFi projects.
|
||
|
||
### ADC2 (UNAVAILABLE When WiFi Active)
|
||
|
||
- ADC2_CH0：GPIO=GPIO4
|
||
- ADC2_CH1：GPIO=GPIO0, Notes=Strapping pin
|
||
- ADC2_CH2：GPIO=GPIO2, Notes=Strapping pin
|
||
- ADC2_CH3：GPIO=GPIO15, Notes=Strapping pin
|
||
- ADC2_CH4：GPIO=GPIO13
|
||
- ADC2_CH5：GPIO=GPIO12, Notes=**DANGER:** Strapping pin
|
||
- ADC2_CH6：GPIO=GPIO14
|
||
- ADC2_CH7：GPIO=GPIO27
|
||
- ADC2_CH8：GPIO=GPIO25, Notes=Also DAC1
|
||
- ADC2_CH9：GPIO=GPIO26, Notes=Also DAC2
|
||
|
||
**Warning:** ADC2 returns invalid readings when WiFi or Bluetooth is active. See esp32-specifics.md for details.
|
||
|
||
---
|
||
|
||
## Touch Channel Mapping
|
||
|
||
ESP32 has 10 capacitive touch sensing channels:
|
||
|
||
- TOUCH0：GPIO=GPIO4
|
||
- TOUCH1：GPIO=GPIO0, Notes=Strapping pin
|
||
- TOUCH2：GPIO=GPIO2, Notes=Strapping pin
|
||
- TOUCH3：GPIO=GPIO15, Notes=Strapping pin
|
||
- TOUCH4：GPIO=GPIO13
|
||
- TOUCH5：GPIO=GPIO12, Notes=**DANGER:** Strapping pin
|
||
- TOUCH6：GPIO=GPIO14
|
||
- TOUCH7：GPIO=GPIO27
|
||
- TOUCH8：GPIO=GPIO33, Notes=Also ADC1
|
||
- TOUCH9：GPIO=GPIO32, Notes=Also ADC1
|
||
|
||
**Notes:**
|
||
- Touch sensing works in deep sleep via ULP coprocessor
|
||
- ESP32-C3 and C6 do NOT have touch sensing capability
|
||
- External components on touch pins affect sensitivity
|
||
|
||
---
|
||
|
||
## RTC GPIO Mapping
|
||
|
||
RTC GPIOs can wake the ESP32 from deep sleep and be controlled by the ULP coprocessor:
|
||
|
||
- RTC_GPIO0：GPIO=GPIO36, ADC=ADC1_CH0, Notes=Input only (SENSOR_VP)
|
||
- RTC_GPIO1：GPIO=GPIO37, ADC=ADC1_CH1, Notes=Not on WROOM-32
|
||
- RTC_GPIO2：GPIO=GPIO38, ADC=ADC1_CH2, Notes=Not on WROOM-32
|
||
- RTC_GPIO3：GPIO=GPIO39, ADC=ADC1_CH3, Notes=Input only (SENSOR_VN)
|
||
- RTC_GPIO4：GPIO=GPIO34, ADC=ADC1_CH6, Notes=Input only
|
||
- RTC_GPIO5：GPIO=GPIO35, ADC=ADC1_CH7, Notes=Input only
|
||
- RTC_GPIO6：GPIO=GPIO25, ADC=ADC2_CH8, Notes=DAC1
|
||
- RTC_GPIO7：GPIO=GPIO26, ADC=ADC2_CH9, Notes=DAC2
|
||
- RTC_GPIO8：GPIO=GPIO33, ADC=ADC1_CH5, Touch=TOUCH8
|
||
- RTC_GPIO9：GPIO=GPIO32, ADC=ADC1_CH4, Touch=TOUCH9
|
||
- RTC_GPIO10：GPIO=GPIO4, ADC=ADC2_CH0, Touch=TOUCH0
|
||
- RTC_GPIO11：GPIO=GPIO0, ADC=ADC2_CH1, Touch=TOUCH1, Notes=Strapping
|
||
- RTC_GPIO12：GPIO=GPIO2, ADC=ADC2_CH2, Touch=TOUCH2, Notes=Strapping
|
||
- RTC_GPIO13：GPIO=GPIO15, ADC=ADC2_CH3, Touch=TOUCH3, Notes=Strapping
|
||
- RTC_GPIO14：GPIO=GPIO13, ADC=ADC2_CH4, Touch=TOUCH4
|
||
- RTC_GPIO15：GPIO=GPIO12, ADC=ADC2_CH5, Touch=TOUCH5, Notes=**DANGER:** Strapping
|
||
- RTC_GPIO16：GPIO=GPIO14, ADC=ADC2_CH6, Touch=TOUCH6
|
||
- RTC_GPIO17：GPIO=GPIO27, ADC=ADC2_CH7, Touch=TOUCH7
|
||
|
||
**Deep Sleep Wake Sources:**
|
||
- EXT0: Single RTC GPIO, level-triggered
|
||
- EXT1: Multiple RTC GPIOs, any-high or all-low trigger
|
||
- Touch pad wake: Any touch channel
|
||
- ULP coprocessor: Programmable wake conditions
|
||
|
||
---
|
||
|
||
## Variant Comparison Table
|
||
|
||
- **CPU Architecture**：ESP32=Xtensa LX6, ESP32-S2=Xtensa LX7, ESP32-S3=Xtensa LX7, ESP32-C3=RISC-V, ESP32-C6=RISC-V
|
||
- **CPU Cores**：ESP32=2, ESP32-S2=1, ESP32-S3=2, ESP32-C3=1, ESP32-C6=1
|
||
- **GPIO Count**：ESP32=34 (0-39), ESP32-S2=43, ESP32-S3=45, ESP32-C3=22 (0-21), ESP32-C6=30
|
||
- **ADC Channels**：ESP32=18, ESP32-S2=20, ESP32-S3=20, ESP32-C3=6, ESP32-C6=7
|
||
- **ADC2/WiFi Conflict**：ESP32=Yes, ESP32-S2=Yes, ESP32-S3=Yes, ESP32-C3=**No**, ESP32-C6=**No**
|
||
- **Touch Channels**：ESP32=10, ESP32-S2=14, ESP32-S3=14, ESP32-C3=**None**, ESP32-C6=**None**
|
||
- **DAC Channels**：ESP32=2, ESP32-S2=2, ESP32-S3=**None**, ESP32-C3=**None**, ESP32-C6=**None**
|
||
- **USB OTG**：ESP32=No, ESP32-S2=Yes (GPIO19/20), ESP32-S3=Yes (GPIO19/20), ESP32-C3=No, ESP32-C6=No
|
||
- **Bluetooth**：ESP32=Classic + BLE, ESP32-S2=**None**, ESP32-S3=BLE 5.0, ESP32-C3=BLE 5.0, ESP32-C6=BLE 5.0
|
||
- **WiFi**：ESP32=802.11 b/g/n, ESP32-S2=802.11 b/g/n, ESP32-S3=802.11 b/g/n, ESP32-C3=802.11 b/g/n, ESP32-C6=**802.11ax (WiFi 6)**
|
||
- **Thread/Zigbee**：ESP32=No, ESP32-S2=No, ESP32-S3=No, ESP32-C3=No, ESP32-C6=**Yes**
|
||
- **Flash Pins**：ESP32=GPIO6-11, ESP32-S2=GPIO26-32, ESP32-S3=GPIO26-32, ESP32-C3=GPIO12-17, ESP32-C6=GPIO24-29
|
||
- **Strapping Pins**：ESP32=0, 2, 5, 12, 15, ESP32-S2=0, 45, 46, ESP32-S3=0, 3, 45, 46, ESP32-C3=2, 8, 9, ESP32-C6=8, 9, 15
|
||
|
||
### Key Variant Notes
|
||
|
||
- **ESP32-C3/C6:** No ADC2/WiFi conflict — all ADC channels work with WiFi
|
||
- **ESP32-S2/S3:** USB OTG requires GPIO19/20 — reserve if using native USB
|
||
- **ESP32-C6:** Only variant with WiFi 6 and Thread/Zigbee support
|
||
- **Touch sensing:** Only original ESP32, S2, and S3 have capacitive touch
|
||
- **DAC:** Only original ESP32 and S2 have analog output capability
|
||
|
||
---
|