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

esp32-peripheral-bringup

Guides bring-up and debugging of ESP32 peripherals — I2C, SPI, UART, ADC and LEDC/PWM — using the ESP-IDF v5 driver APIs, chip-correct pin choices, and a step-by-step wiring → config → probe → speed-up procedure. Use when the user says "I2C sensor not responding", "i2c ESP_ERR_TIMEOUT", "no ACK", "I2C scan finds nothing", "SPI returns 0xFF", "SPI display blank", "UART garbage characters", "uart_read_bytes returns nothing", "ADC reads wrong value", "adc_oneshot", "analogRead with Wi-Fi", "PWM / LEDC not working", "set duty", "bring up a new sensor", or "connect a peripheral" on ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other Espressif chips.

agodianel · 已有静态检查记录

安装与使用

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

npx skills add agodianel/esp32-claude-workbench --skill esp32-peripheral-bringup

技能说明


name: esp32-peripheral-bringup description: Guides bring-up and debugging of ESP32 peripherals — I2C, SPI, UART, ADC and LEDC/PWM — using the ESP-IDF v5 driver APIs, chip-correct pin choices, and a step-by-step wiring → config → probe → speed-up procedure. Use when the user says "I2C sensor not responding", "i2c ESP_ERR_TIMEOUT", "no ACK", "I2C scan finds nothing", "SPI returns 0xFF", "SPI display blank", "UART garbage characters", "uart_read_bytes returns nothing", "ADC reads wrong value", "adc_oneshot", "analogRead with Wi-Fi", "PWM / LEDC not working", "set duty", "bring up a new sensor", or "connect a peripheral" on ESP32, ESP32-S3, ESP32-C3, ESP32-C6 or other Espressif chips. license: MIT metadata: source: esp32-workbench version: "0.2.0"

ESP32 Peripheral Bring-up

Bring a bus up in small, verifiable steps: pins → electrical → minimal config → probe → read known register → full speed → error handling.

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
Is this pin usable on this chip?chip_info, pin_auditesp32wb chip <target>, esp32wb pins .
Driver API / limits for the target (always before writing driver code)search_esp_docsesp32wb docs search "i2c master probe" --target T (index once: esp32wb docs index, needs pip install 'esp32-workbench[docs]')
Summarise error outputlog_summaryesp32wb logs monitor.log

Before writing driver code

  1. Target chip + ESP-IDF version (API generation differs: v5.x has new I2C master, esp_adc oneshot, etc.).
  2. Pin plan checked with esp32wb pins . — no flash/PSRAM/USB/console pins, strapping pins only with a reason, input-only pins only as inputs.
  3. Peripheral instance count for the chip (number of I2C/SPI/UART ports, LEDC channels, ADC units differs per target) — check docs, do not assume classic ESP32.
  4. Device datasheet: voltage levels (3.3 V I/O — never 5 V into a GPIO), address/mode, timing, power-up delay.
  5. An implementation contract exists for the change.

Per-peripheral quick guide

I2C

  • External pull-ups on SDA/SCL (typ. 2.2–4.7 kΩ to 3.3 V); internal pulls are too weak.
  • Start at 100 kHz; use i2c_master_probe() (new driver) to scan.
  • 7-bit addresses (datasheet 0xD0 8-bit write address = 0x68).
  • Don't mix the legacy driver/i2c.h and new driver/i2c_master.h APIs in one build unless the IDF version explicitly allows it.
  • Full procedure: I2C bring-up.

SPI

  • Mode (CPOL/CPHA) from the device datasheet — the #1 failure cause.
  • Start at 1 MHz; .length is in bits.
  • IOMUX pins allow the highest clock; GPIO-matrix routing lowers the max — check the SPI master timing section for your chip.
  • DMA buffers from MALLOC_CAP_DMA memory.
  • Full procedure: SPI bring-up.

UART

  • Match baud, data bits, parity, stop bits, and flow control on both ends; cross TX→RX.
  • Do not take UART0 console pins unless the console is moved.
  • RX buffer passed to uart_driver_install() must exceed the hardware FIFO.
  • Full procedure: UART bring-up.

ADC

  • Use esp_adc (adc_oneshot_* + adc_cali_*) on IDF v5; legacy driver/adc.h is deprecated.
  • ADC2 + Wi-Fi is chip-specific (classic ESP32: unusable with Wi-Fi; S2/S3: arbitrated, reads can fail; C3: ADC2 oneshot unsupported) → prefer ADC1.
  • Calibrate and report millivolts, not raw counts; attenuation sets the input range.
  • Full procedure: ADC bring-up.

LEDC (PWM)

  • LEDC_HIGH_SPEED_MODE exists only on classic ESP32; other chips use LEDC_LOW_SPEED_MODE.
  • Frequency × 2^resolution must be achievable from the timer clock source.
  • Full procedure: LEDC bring-up.

Bring-up procedure (all buses)

  1. Power and wiring: measure supply at the device, common ground, short wires.
  2. Minimal config at the slowest sensible speed, explicit pins (never rely on defaults).
  3. Probe: I2C probe / SPI read of a WHO_AM_I or ID register / UART loopback / ADC on a known voltage / LEDC on a scope or LED.
  4. Check every esp_err_t; log with esp_err_to_name().
  5. Scale up: target speed, DMA, interrupts, multiple devices.
  6. Harden: timeouts, retries, bus recovery, de-init path, mutex if the bus is shared between tasks.
  7. Evidence: serial log of probe + readings, logic-analyzer capture if available.

Report

# Bring-up — <device> on <bus> (target: <chip>, IDF <ver>)
| Signal | GPIO | Chip category (esp32wb) | Notes |
## Configuration (speed, mode, address, pulls)
## Results (probe / ID register / readings, with log excerpts)
## Issues found and fixes
## Not verified (e.g. no scope available)

Rules

  • Never hallucinate peripheral limits; search the docs for the target first.
  • Pin choices must pass esp32wb pins for the configured target.
  • Any code change goes through the mission/contract workflow.