Help develop, build, flash, and debug ESP32/ESP8266 firmware using Espressif ESP-IDF on Linux/WSL. Use when the user asks about ESP-IDF project setup, config...
---
name: esp-idf-helper
description: Help develop, build, flash, and debug ESP32/ESP8266 firmware using Espressif ESP-IDF on Linux/WSL. Use when the user asks about ESP-IDF project setup, configuring targets, menuconfig, building, flashing via esptool/idf.py, serial monitor, partition tables, sdkconfig, troubleshooting build/flash/monitor errors, or automating common idf.py workflows from the command line.
homepage: https://github.com/espressif/esp-idf
metadata:
{
"esp-idf-helper":
{
"emoji": "๐ค",
"requires": { "bins": ["idf.py"], "env": ["IDF_PATH"] },
"primaryEnv": "IDF_PATH",
},
}
---
# esp-idf-helper Skill
Provide a repeatable, command-line-first workflow for ESP-IDF development on Linux/WSL: configure โ build โ flash โ monitor โ debug/troubleshoot.
## Quick Reference
```bash
# 1) Source the ESP-IDF environment (once per terminal session)
. $IDF_PATH/export.sh
# 1.1) Enable ccache to speed up compilation (recommended)
export IDF_CCACHE_ENABLE=1
# 2) Go to your project and build
cd /path/to/your/project
idf.py set-target <target> # Set target chip (once per project)
idf.py build # Compile
# 3) flash
idf.py -p <PORT> -b <BAUD> flash # Flash to device (optional)
```
### Common commands
- `idf.py --help` โ Help
- `idf.py set-target <target>` โ Set chip target: esp32, esp32s2, esp32s3, esp32c3, esp32p4
- `idf.py menuconfig` โ Configure project settings (**must run in a new terminal window**)
- `idf.py build` โ Build the project
- `idf.py update-dependencies` โ Update project component dependencies
- `idf.py partition-table` โ Build partition table and print partition entries
- `idf.py partition-table-flash` โ Flash partition table to device
- `idf.py storage-flash` โ Flash storage filesystem partition
- `idf.py size` โ Show firmware size information
- `idf.py -p <PORT> -b <BAUD> flash` โ Flash firmware (default baud: 460800)
- `idf.py -p <PORT> monitor` โ Open serial monitor
- `idf.py -p <PORT> -b <BAUD> monitor` โ Open serial monitor with specific baud (e.g. 460800)
- `idf.py -p <PORT> -b <BAUD> flash monitor` โ Flash then monitor
## Component Management
ESP-IDF projects can include external components from the **ESP Component Registry**.
- **Registry Website:** https://components.espressif.com/components
- **Search components:** Browse or search for components on the registry website
### Component Commands
- `idf.py add-dependency "<component>"` โ Add a component dependency to `idf_component.yml`
- `idf.py update-dependencies` โ Download and update all project dependencies
### Component Management Workflow
```bash
# 1) Add a dependency to your project
idf.py add-dependency "<component>"
# 2) Update dependencies (downloads components to managed_components/)
idf.py update-dependencies
```
**Note:** Dependencies are recorded in `idf_component.yml` in your project's main component directory (`main/`).
## Bundled resources
### references/
- `references/esp-idf-cli.md` โ concise command patterns + what to paste back when reporting errors.
- `references/idf-py-help.txt` โ captured `idf.py --help` output for quick lookup/search.
To refresh the help text for your installed ESP-IDF version, run:
- `scripts/capture_idf_help.sh`
### assets/
Not used by default.
## Serial Port Management (WSL2)
For WSL2 users, USB serial devices need to be attached via **usbipd** to be accessible in WSL.
### List Available Serial Devices
```bash
scripts/usbipd_attach_serial.sh --list
```
Shows all connected USB serial devices (CH340, CH343, CP210, FTDI, etc.).
**Note:** This script runs in WSL2 and uses `powershell.exe` to communicate with Windows usbipd.
### Bind/Attach All Serial Devices
```bash
# Bind and attach all COM port devices
scripts/usbipd_attach_serial.sh --keyword "COM"
# Or attach specific device by busid
scripts/usbipd_attach_serial.sh --busid 3-2
# Or filter by device type
scripts/usbipd_attach_serial.sh --keyword "CH343"
scripts/usbipd_attach_serial.sh --keyword "ESP32"
```
### Serial Port Script Options
- `--list` โ List all matching serial devices and exit
- `--busid <BUSID>` โ Specify device bus ID (e.g., `3-2`)
- `--keyword <TEXT>` โ Filter devices by keyword (e.g., `COM`, `CH343`, `ESP32`)
- `--bind` โ Bind only (skip attach), useful for first-time setup with admin privileges
- `--distro <DISTRO>` โ Specify WSL distribution name
- `--dry-run` โ Print commands without executing
### Typical Workflow
```bash
# 1. Check available devices
scripts/usbipd_attach_serial.sh --list
# 2. Attach all serial devices
scripts/usbipd_attach_serial.sh --keyword "COM"
# 3. Verify devices in WSL
ls -la /dev/ttyACM* /dev/ttyUSB*
# 4. Use with idf.py
idf.py -p /dev/ttyACM0 flash monitor
```
**Note:** This script runs in WSL2 and internally uses `powershell.exe` to communicate with Windows usbipd service.
### Troubleshooting: powershell.exe not found
If you encounter `powershell.exe: command not found`, the Windows paths are not in your PATH environment variable.
**Quick Fix (current session only):**
```bash
export PATH="$PATH:/mnt/c/Windows/System32:/mnt/c/Windows/System32/WindowsPowerShell/v1.0"
~/skills/esp-idf-helper/scripts/usbipd_attach_serial.sh --list
```
**Permanent Fix (add to ~/.bashrc):**
```bash
echo 'export PATH="$PATH:/mnt/c/Windows/System32:/mnt/c/Windows/System32/WindowsPowerShell/v1.0:/mnt/c/Windows/SysWOW64"' >> ~/.bashrc
source ~/.bashrc
```
## Firmware Packaging
Pack ESP-IDF build output into a distributable firmware package with cross-platform flash scripts.
### Usage
```bash
scripts/pack_firmware.sh <build_directory>
```
### Example
```bash
# After building your project
idf.py build
# Create firmware package
scripts/pack_firmware.sh ./build
# Output: build/firmware_package/ and build/esp_firmware_YYYYMMDD_HHMMSS.zip
```
### Generated Package Contents
| File | Description |
|------|-------------|
| `flash.sh` | Linux/Mac flash script with retry and parallel support |
| `flash.bat` | Windows multi-port flash launcher |
| `flash_one.bat` | Windows single-port flash with retry |
| `mac_addresses.txt` | Recorded MAC addresses (deduplicated) |
| `*.bin` | Firmware binary files |
| `tools/esptool/esptool.exe` | Windows esptool executable |
| `README.txt` | Usage instructions |
### Flash Script Features
- **Auto-retry**: 3 attempts on failure
- **Parallel flashing**: Multiple devices simultaneously
- **MAC recording**: Automatic MAC address extraction and deduplication
- **Cross-platform**: Linux/Mac/Windows support
### Production Workflow
```bash
# 1. Build the project
idf.py build
# 2. Package firmware
scripts/pack_firmware.sh ./build
# 3. Distribute the ZIP to production line
# Production team runs: flash.bat all (Windows) or ./flash.sh /dev/ttyUSB* (Linux)
```don't have the plugin yet? install it then click "run inline in claude" again.