suyushi/esp32-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial: knowledge base

Browse Source
This commit is contained in:
suyushi
2026-08-05 17:25:09 +08:00
parent bfabe83832
commit 5700eb4115
35 changed files with 5140 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
platforms_esp32-pins.md
+318
View File
@@ -0,0 +1,318 @@
# 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
---