Esp32 Pin Audit

ESP32 Pin Audit

Systematically audit GPIO pin usage across the project to detect conflicts, reserved pin misuse, and undocumented assignments.

When to Use

• Before adding new peripheral code.
• During architecture review.
• When debugging mysterious hardware behavior.
• Before release.

Steps

1. Collect All Pin Declarations

Search the project for pin definitions:

# Macro definitions
grep -rn "#define.*GPIO\|#define.*PIN\|#define.*SDA\|#define.*SCL\|#define.*MOSI\|#define.*MISO\|#define.*CS\|#define.*CLK" --include="*.h" --include="*.c"

# GPIO_NUM usage
grep -rn "GPIO_NUM_" --include="*.c" --include="*.h"

# Kconfig GPIO options
grep -rn "CONFIG_.*GPIO\|CONFIG_.*PIN" sdkconfig.defaults sdkconfig 2>/dev/null

2. Check Reserved Pins

Flag violations against these reserved pins:

| GPIO | Restriction | Reason | |------|-------------|--------| | 0 | Boot strapping | Must be HIGH for normal boot, LOW for download | | 1 | UART0 TX | Default serial output | | 2 | Boot strapping | Must be LOW during flash | | 3 | UART0 RX | Default serial input | | 6–11 | FORBIDDEN | Connected to internal SPI flash | | 12 | Boot strapping | MTDI — affects flash voltage | | 15 | Boot strapping | MTDO — affects debug output | | 34–39 | Input-only | No output capability, no pull-up/pull-down |

3. Detect Conflicts

Build a pin allocation table and check for:

• Double assignment: Same GPIO used by two different peripherals.
• Bus conflicts: I2C and SPI sharing the same pins.
• ADC/DAC conflicts: ADC2 channels unusable when Wi-Fi is active.
• Strapping conflicts: Boot pins used without awareness.

4. Verify Pull-Up/Pull-Down Configuration

For I2C lines:

• External pull-ups are required. Internal pull-ups are too weak for reliable I2C.
• Flag if only internal pull-ups are configured for I2C.

For inputs with no external circuitry:

• Verify pull-up or pull-down is configured to avoid floating pins.

5. Check Documentation

Compare actual code pin usage against:

• Pin map comments in source files.
• README or documentation references.
• Schematic references if available.

Flag any drift between documented and actual usage.

6. Generate Audit Report

# Pin Audit Report

## Pin Allocation Table
| GPIO | Function | Component | Direction | Pull | Notes |
|------|----------|-----------|-----------|------|-------|

## Violations
- [ ] [Description of violation]

## Conflicts
- [ ] [Description of conflict]

## Warnings
- [ ] [Potential issues to investigate]

## Documentation Drift
- [ ] [Documented vs. actual usage]

ADC2 Wi-Fi Warning

Critical: ADC2 channels (GPIO 0, 2, 4, 12, 13, 14, 15, 25, 26, 27) cannot be used while Wi-Fi is active. Always flag ADC2 usage in Wi-Fi-enabled projects.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agodianel
• Source: agodianel/esp32-claude-workbench
• License: MIT

Install and usage instructions live in the source repository linked above.