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

CODEBLOCK0

Common commands

• - idf.py --help — Help
• INLINECODE1 — Set chip target: esp32, esp32s2, esp32s3, esp32c3, esp32p4
• INLINECODE2 — Configure project settings (must run in a new terminal window)
• INLINECODE3 — Build the project
• INLINECODE4 — Update project component dependencies
• INLINECODE5 — Build partition table and print partition entries
• INLINECODE6 — Flash partition table to device
• INLINECODE7 — Flash storage filesystem partition
• INLINECODE8 — Show firmware size information
• INLINECODE9 — Flash firmware (default baud: 460800)
• INLINECODE10 — Open serial monitor
• INLINECODE11 — Open serial monitor with specific baud (e.g. 460800)
• INLINECODE12 — 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 INLINECODE14
• INLINECODE15 — Download and update all project dependencies

Component Management Workflow

CODEBLOCK1

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.
• INLINECODE19 — captured idf.py --help output for quick lookup/search.

To refresh the help text for your installed ESP-IDF version, run:

• - INLINECODE21

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

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

CODEBLOCK3

Serial Port Script Options

• - --list — List all matching serial devices and exit
• INLINECODE24 — Specify device bus ID (e.g., 3-2)
• INLINECODE26 — Filter devices by keyword (e.g., COM, CH343, ESP32)
• INLINECODE30 — Bind only (skip attach), useful for first-time setup with admin privileges
• INLINECODE31 — Specify WSL distribution name
• INLINECODE32 — Print commands without executing

Typical Workflow

CODEBLOCK4

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):
CODEBLOCK5

Permanent Fix (add to ~/.bashrc):
CODEBLOCK6

Firmware Packaging

Pack ESP-IDF build output into a distributable firmware package with cross-platform flash scripts.

Usage

CODEBLOCK7

Example

CODEBLOCK8

Generated Package Contents

File	Description
INLINECODE35	Linux/Mac flash script with retry and parallel support
INLINECODE36

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

CODEBLOCK9