idf.py 常用命令

idf.py 命令工具

与 CMake 的关系

idf.py 是 ESP-IDF 的主要命令行工具，它是 CMake 构建系统的上层封装：

• 底层：CMake + Ninja 构建系统
• 中间层：ESP-IDF 的 CMake 扩展和脚本
• 顶层：idf.py 提供统一的用户接口

工作流程：

idf.py → Python 脚本 → CMake 配置 → Ninja 编译 → 生成固件

常用命令

项目管理命令

# 设置目标芯片
idf.py set-target esp32
idf.py set-target esp32s3
idf.py set-target esp32c3

# 创建新项目（从模板）
idf.py create-project my_project

# 添加组件依赖
idf.py add-dependency "espressif/led_strip"

配置命令

# 打开配置菜单
idf.py menuconfig

# 重新配置（清除缓存的配置）
idf.py reconfigure

# 保存当前配置为默认配置
idf.py save-defconfig

构建命令

# 完整构建
idf.py build

# 仅构建指定组件
idf.py build --component main

# 清理构建文件
idf.py clean

# 完全清理（包括配置）
idf.py fullclean

烧录命令

# 自动检测端口并烧录
idf.py flash

# 指定端口烧录
idf.py -p /dev/ttyUSB0 flash
idf.py -p COM3 flash  # Windows

# 仅烧录应用程序（不包括 bootloader）
idf.py app-flash

# 擦除整个 Flash
idf.py erase-flash

监控命令

# 串口监控
idf.py monitor

# 指定端口监控
idf.py -p /dev/ttyUSB0 monitor

# 烧录后直接监控
idf.py flash monitor

# 退出监控：Ctrl+]

调试命令

# 生成调试信息
idf.py build --debug

# 启动 GDB 调试
idf.py gdb

# 启动 OpenOCD
idf.py openocd

其他实用命令

# 显示项目大小信息
idf.py size
idf.py size-components  # 按组件显示大小

# 显示分区表
idf.py partition-table

# 生成编译数据库（用于 IDE）
idf.py compiledb

# 显示帮助
idf.py --help

命令选项

# 全局选项
idf.py -p PORT     # 指定串口
idf.py -b BAUD     # 指定波特率
idf.py -C DIR      # 改变工作目录
idf.py -v          # 详细输出
idf.py --dry-run   # 显示将要执行的命令但不执行

# 示例
idf.py -p /dev/ttyUSB0 -b 921600 flash monitor

开发工作流程

1. 环境准备

# 安装 ESP-IDF
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh

# 设置环境变量
. ./export.sh

2. 创建项目

# 从示例创建项目
cp -r $IDF_PATH/examples/get-started/hello_world ~/my_project
cd ~/my_project

# 或使用命令创建
idf.py create-project my_project

3. 配置项目

# 设置目标芯片
idf.py set-target esp32s3

# 配置项目参数
idf.py menuconfig

4. 开发与测试

# 编译
idf.py build

# 烧录并监控
idf.py -p /dev/ttyUSB0 flash monitor

# 仅监控（用于调试）
idf.py monitor

5. 调试与优化

# 查看大小信息
idf.py size-components

# 清理重构建
idf.py clean build

# 生成调试信息
idf.py build --debug