SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsesp32-peripherals

esp32-peripherals

General & other

View repository

Updated 10-15 21:48

About this skill

ESP32 Peripherals and Drivers (esp32-peripherals)

This Skill determines "which peripheral to use, which driver interface, and which pin to connect to."Hardware contract first: pins/muxing/pull-ups/strapping are always based on the chip datasheet or board schematic; fabrication is prohibited. The driver interface follows the v6.x new componentized direction; legacy drivers were removed in v6.0 (baseline high confidence).

Determine Task Type

  1. Select peripheral/driver interface — Requirements map to GPIO/I2C/SPI/UART/ADC/PWM(LEDC)/RMT, and confirm the v6.x new interface → decision table.
  2. Wiring and pin assignment — Check datasheet/schematic to determine pins and pull-ups → follow the hardware contract process (Workflow 1).
  3. Bus cannot be debugged — I2C no ACK, SPI garbled screen, UART garbled characters → Workflow 2 (check electrical and configuration first, then check code).
  4. Concurrency issues(ISR and driver share data) → hand off to esp32-freertos；crash forensics → esp32-debug。

Preflight (verify at runtime first)

idf.py --version                          # v6.x → 新式驱动方向；v5 → 提示迁移路径
grep -rn "#include \"driver/" main/       # 工程现有驱动头文件（发现 legacy 痕迹）
grep -m1 "CONFIG_IDF_TARGET" sdkconfig    # 芯片 target，与实物核对
  • Verify target against the physical chip/schematic before discussing pins.
  • The exact header file names are based on thelocal IDF source treeand the official API reference; this document only marks verified directions.

Offline Baseline

  • Driver migration facts are based on a dated baseline: ESP-IDF v6.1, walk through 2026-09-02, no automatic updates.
  • Baseline high confidence: v6.0 removed legacy drivers (naming ADC, I2S, Timer, etc.);driver/i2c_master.h（esp_driver_i2c component) is the I2C master new interface verified on the day of the official stable documentation.
  • The remaining peripheral header file names were not fetched one by one—when citing, mark "verify at runtime", do not fill in from memory.

Contracts (hardware contract—red line of this Skill)

  • Pin numbering and muxing: Always read the target chip's datasheet / technical reference manual / IO MUX table, or the board schematic;if uncertain, stop; do not give "common values"。
  • Strapping pins: Their power-on default values and external pull-up/pull-down affect the boot mode—do not fabricate strapping pin values; when involved, check the datasheet before wiring.
  • Pull-up/pull-down: Whether a GPIO can have an internal pull-up and how strong its drive capability is are based on the datasheet; whether I2C requires external pull-ups is calculated according to the bus electrical characteristics.
  • Device side: I2C slave address, SPI mode/polarity, UART baud rate and voltage level are based on the peripheral device manual (remind the user to verify 3.3V/5V level adaptation).

Peripheral decision table

Peripheral When to use v6.x driver direction (see bus-quickref / adc-caveats for details)
GPIO Buttons/LEDs/simple digital switches, edge interrupts General GPIO interface; header file names verified at runtime
I2C Low-speed sensors/EEPROM, multiple slaves sharing the bus New master:driver/i2c_master.h(esp_driver_i2c, verified)
SPI High-speed devices (screen/Flash/ADC), full duplex New master driver direction; header file names verified at runtime
UART Communicate with external modules/debug serial port General UART driver + esptoolseparate from the console port that /monitor depends on
ADC Read analog values (potentiometer/battery voltage) legacy ADC has been removed in v6.0—use the new interface (see adc-caveats, marked for verification)
PWM Dimming/servo/buzzer → LEDC LEDC peripheral; header file names verified at runtime
RMT Infrared transmit/receive, WS2812 color LEDs, precise bit timing RMT peripheral (preferred over GPIO toggling for precise-timing scenarios); marked for verification

Capability Boundaries + Hand-off

User Intent Skill
Project skeleton/build and flash/partition table esp32-idf
IDF version upgrade / v5→v6 project migration esp32-idf
Driver task and ISR concurrency model esp32-freertos
Crash forensics after locating a sampling anomaly esp32-debug
Pin retention/power consumption during sleep esp32-lowpower
Whether the chip has this peripheral (selection layer) esp32-variants
Bus timing measurement (logic analyzer/oscilloscope) fw-hil-testing

Workflow 1: Wiring and pin assignment

  1. Confirm the target matches the physical chip (Preflight).
    • Pin placement: the verified pin numbers must beexplicitly written into the driver initialization configuration/parameters(or menuconfig), and must not be left blank to be guessed by default values.
  2. Open the IO MUX/pin definition chapter of the chip datasheet and list candidate pins; note which are Strapping pins and avoid them.
  3. Check the board schematic to confirm the actual pin connections and the current state of pull-up/pull-down resistors.
  4. Write "pin number → peripheral → electrical conditions" as a checklist for the user to confirm before writing code.
  5. If the datasheet conflicts with online tutorials:the datasheet takes precedence, and remind that the tutorial may correspond to a different chip.

Workflow 2: Bus not working

  1. Electrical first, then code: power supply, common ground, pull-ups, level matching, wire length.
  2. I2C no ACK: verify the 7-bit/8-bit address notation, whether the speed exceeds the device limit, and whether the bus is pulled high by pull-ups (if possible, use a logic analyzer to view the waveform → fw-hil-testing).
  3. SPI anomalies: verify mode (CPOL/CPHA) and byte order, chip select timing, and try reducing the speed.
  4. UART garbled data: ensure both ends have matching baud rate/parity; confirm you are measuring the same TTL port rather than RS232 levels.
  5. Code-side troubleshooting: confirm that the included header is the new v6.x driver header (legacy headers have been removed in v6.0, see bus-quickref）。

Validation Gates

  • idf.py build passes, with no legacy header warnings.
  • The pin checklist matches the datasheet/schematic item by item; Strapping pins are not misused.
  • Bus communication has evidence: device response/correct data/oscilloscope waveform—only one of these three counts as working.
  • When there is no hardware evidence, mark Build Verification Only。

Pitfalls

  1. Do notanswer questions like "the default I2C pin numbers for a certain chip" without verification—most ESP-IDF pins can be matrix-mapped, and there is no cross-board uniform "default"; it must be confirmed with the datasheet + the user's schematic (a typical refusal scenario).
  2. Do notcontinue using legacy driver APIs in a v6.x project (ADC/I2S/Timer etc. have been removed in v6.0).
  3. Do notfabricate Strapping pin default values or "just pick a GPIO"—the power-on state depends on these pins.
  4. Do notmix 7-bit/8-bit notations for I2C addresses, causing false failures of "address does not exist".
  5. Do notcall blocking bus transfers directly in an ISR—the concurrency model is handed over to esp32-freertos。

Official Sources

Privacy

This Skill does not collect or send user data or device credentials; pin and schematic information is used only for local analysis of the current task; access to official links complies with the user environment's network policy.