Case 01889

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

# 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

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

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

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)