跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

esp32-pin-audit

Audits GPIO assignments in ESP32-family firmware against the verified pin facts of the actual target chip and board, flagging flash/PSRAM pins, strapping pins, input-only pins, USB-Serial-JTAG and UART0 console pins, JTAG pins, ADC2/Wi-Fi conflicts, double assignments and pin-map drift. Use when the user asks "which pins can I use", "is GPIO 12 safe", "check my pinout", "pin conflict", "strapping pin", "board won't boot after wiring", "can't flash after connecting a sensor", "ADC2 with Wi-Fi", "input-only pin", "/pin-audit", or before adding any GPIO, I2C, SPI, UART, ADC or LEDC code on ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 or ESP32-P4.

agodianel · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add agodianel/esp32-claude-workbench --skill esp32-pin-audit

技能说明


name: esp32-pin-audit description: Audits GPIO assignments in ESP32-family firmware against the verified pin facts of the actual target chip and board, flagging flash/PSRAM pins, strapping pins, input-only pins, USB-Serial-JTAG and UART0 console pins, JTAG pins, ADC2/Wi-Fi conflicts, double assignments and pin-map drift. Use when the user asks "which pins can I use", "is GPIO 12 safe", "check my pinout", "pin conflict", "strapping pin", "board won't boot after wiring", "can't flash after connecting a sensor", "ADC2 with Wi-Fi", "input-only pin", "/pin-audit", or before adding any GPIO, I2C, SPI, UART, ADC or LEDC code on ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 or ESP32-P4. license: MIT metadata: source: esp32-workbench version: "0.2.0"

ESP32 Pin Audit

Pin rules are chip-specific. GPIO 6–11 are flash pins on classic ESP32 but ordinary GPIOs on ESP32-S3; GPIO 34–39 are input-only on classic ESP32 but bidirectional on ESP32-S3. Never apply one chip's table to another.

Tools

If the esp32-workbench MCP server is connected, call its tools; otherwise run the CLI. If esp32wb is not on PATH, use uvx --from git+https://github.com/agodianel/esp32-claude-workbench esp32wb <args>. Add --json for machine-readable output.

NeedMCP toolCLI
Audit all GPIO usage (target auto-detected from CONFIG_IDF_TARGET)pin_auditesp32wb pins <path> [--target T]
Verified pin facts + Espressif source linkschip_infoesp32wb chip <target> (no arg lists targets)
Anything the chip table does not coversearch_esp_docsesp32wb docs search "<query>" --target T

Targets: esp32 esp32s2 esp32s3 esp32c2 esp32c3 esp32c5 esp32c6 esp32h2 esp32p4.

Steps

1. Establish target, module and board

  • Target from CONFIG_IDF_TARGET in sdkconfig / sdkconfig.defaults. If none is set, ESP-IDF defaults to esp32; state that assumption in the report.
  • Module/variant matters: flash and PSRAM type (quad vs octal, in-package vs external) change which pins are reserved. Check CONFIG_SPIRAM* and CONFIG_ESPTOOLPY_OCT_FLASH / octal PSRAM settings.
  • Board: if a profile exists (see References below), use it. Otherwise ask for the schematic. On-board peripherals (LEDs, buttons, displays, power-management chips) occupy pins even if the code never mentions them.

2. Run the audit tool

esp32wb pins . — it collects GPIO_NUM_*, #define *_PIN/_GPIO, Kconfig GPIO options and driver config structs, then checks them against the chip table. Include its findings verbatim; add your own analysis on top.

If the tool is unavailable, collect manually:

grep -rnE "GPIO_NUM_[0-9]+|#define\s+\w*(GPIO|PIN|SDA|SCL|MOSI|MISO|SCLK|CLK|CS|TX|RX)\w*\s+[0-9]+" \
  --include=*.c --include=*.h --include=*.cpp .
grep -rn "CONFIG_.*\(GPIO\|PIN\)" sdkconfig sdkconfig.defaults* 2>/dev/null

and get the chip facts from esp32wb chip <target> or the Espressif datasheet.

3. Check every pin against the chip's categories

For each GPIO in use, look up the target's facts and classify:

CategorySeverityWhat to check
Not a GPIO on this chipERRORNumber missing from the chip's GPIO list (e.g. S3 has no GPIO22–25)
Flash SPI pinsERRORNever use. Set differs per chip
PSRAM pinsERROR if PSRAM enabledIncludes octal-mode extras on S3
Input-onlyERROR if used as output or with internal pullsClassic ESP32: 34–39 (no internal pulls). S2: GPIO46. S3/C-series: none
StrappingWARNExternal circuits must not force the wrong level at reset; note the boot function
USB D-/D+ (USB-Serial-JTAG / OTG)WARNReusing them disables USB console/JTAG/flashing over USB. Present on S2/S3/C3/C5/C6/H2/P4
UART0 console TX/RXWARNBreaks logs/flashing over UART unless the console is moved
JTAG pinsWARN if hardware debugging is used
ADC2 + Wi-Fisee below

4. ADC2 and Wi-Fi (chip-dependent)

  • Classic ESP32: ADC2 pins cannot be used while Wi-Fi is in use — ERROR. Move analog inputs to ADC1.
  • ESP32-S2 / ESP32-S3: ADC2 is shared with Wi-Fi and the driver arbitrates; adc_oneshot_read() can fail (returns an error) while Wi-Fi holds ADC2 — WARN, require retry/error handling or move to ADC1.
  • ESP32-C3: ADC2 (GPIO5) oneshot is no longer supported by current ESP-IDF due to a hardware erratum — flag any ADC2 use regardless of Wi-Fi.
  • Other chips: check esp32wb chip <target> (field "ADC2 + Wi-Fi" and notes) — several have no ADC2 at all.

5. Conflicts and electrical checks

  • Same GPIO assigned to two functions (including board-fixed functions).
  • Buses sharing pins unintentionally (I2C vs SPI vs UART).
  • I2C lines: external pull-ups required; internal pull-ups are too weak for reliable I2C. Flag configs relying only on *_pullup_en.
  • Floating inputs: buttons/sensors without external or internal pull.
  • Voltage domain: some pins run at the flash/PSRAM voltage on 1.8 V parts (e.g. ESP32-S3 GPIO47/48 on R8V/R16V variants) — check esp32wb chip.

6. Documentation drift

Compare code against pin_map.h, README pin tables, board profile and schematic. Every assignment must appear in one documented pin map (project rule).

Report

# Pin Audit — <project> (target: <chip>, board: <board>, module: <module>)
Evidence: `esp32wb pins` output + `esp32wb chip <target>` sources.

## Pin Allocation
| GPIO | Function | Defined in | Direction | Pull | Chip category |
## Errors (must fix)
## Warnings (strapping / USB / console / JTAG / ADC2)
## Conflicts
## Documentation drift
## Unknowns (facts not confirmed for this chip/board)

Use plain words (ERROR, WARN, OK) rather than emoji so the report renders in every agent and terminal.

References

  • Chip-by-chip hardware limitations
  • Board profiles ([ind
阅读完整来源 ↗