Skills esp-idf-helper

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.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/547895019/esp-idf-helper" ~/.claude/skills/clawdbot-skills-esp-idf-helper && rm -rf "$T"

manifest: skills/547895019/esp-idf-helper/SKILL.md

source content

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)