ESP-IDF Helper

---

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

# 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     # Set target chip (once per project)
idf.py build                 # Compile
3) flash
idf.py -p  -b  flash  # Flash to device (optional)

Common commands

idf.py --help — Help

idf.py set-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 -b flash — Flash firmware (default baud: 460800)

idf.py -p monitor — Open serial monitor

idf.py -p -b monitor — Open serial monitor with specific baud (e.g. 460800)

idf.py -p -b 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 "" — Add a component dependency to idf_component.yml

idf.py update-dependencies — Download and update all project dependencies

Component Management Workflow

# 1) Add a dependency to your project
idf.py add-dependency ""
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

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

# 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 — Specify device bus ID (e.g., 3-2)

--keyword — Filter devices by keyword (e.g., COM, CH343, ESP32)

--bind — Bind only (skip attach), useful for first-time setup with admin privileges

--distro — Specify WSL distribution name

--dry-run — Print commands without executing

Typical Workflow

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

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

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

scripts/pack_firmware.sh 

Example

# 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

# 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)

# 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

# 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)