ESP-IDF
- espressif/esp-idf
- Apache-2.0, C/C++, CMake
- Espressif SoC 的官方 IoT 开发框架，提供 FreeRTOS、驱动、网络协议栈、构建、烧录和调试工具。
ESP-IDF 项目以 CMake 组织，idf.py 统一调用 CMake、Ninja、esptool 和监视器。先固定目标芯片和 ESP-IDF 版本，再提交与该目标对应的配置默认值；不要复用不同 target 的 build/ 目录。
开发语言
- C：ESP-IDF 的主体与大部分官方 API 均以 C 为中心。新项目若需要直接使用驱动、FreeRTOS、网络协议栈和官方示例，优先从 C 开始；组件的
CMakeLists.txt通过idf_component_register(...)组织 C 源文件与依赖。 - C++：ESP-IDF 支持 C++ application 和 component，可与 C API 混合使用。C/C++ 互调时在公共头文件中正确处理
extern "C"；将 C 示例迁到 C++ 前，检查 designated initializer 等语言规则差异。 - C++ 运行时特性：异常和 RTTI 默认关闭，需要时通过相应
CONFIG_COMPILER_CXX_*配置显式启用，并评估 flash、RAM、stack 和异常路径的代价。默认 C++ language standard 取决于 ESP-IDF 版本与 toolchain；组件可在自身CMakeLists.txt显式设置，不应无依据地假定。 - CMake：不是 firmware 的运行时语言，但它是 ESP-IDF component、依赖、编译选项和链接行为的声明层。构建逻辑应留在
CMakeLists.txt，不要把 target-specific 编译行为散落到 shell script。 - Python：用于
idf.py、Component Manager、生成脚本、测试和 CI 自动化；通常不作为 ESP-IDF firmware 应用的运行时语言。项目脚本应使用 ESP-IDF 已激活环境提供的 Python 依赖。 - Rust、Arduino C++、MicroPython：属于 Espressif 生态中的其他开发入口或上层框架。它们可能复用 ESP-IDF 的底层能力，但其依赖管理、运行时和调试流程不应与原生 ESP-IDF C/C++ 项目混为一谈。
安装
- 推荐：使用 Espressif Installation Manager (EIM) 安装稳定版 ESP-IDF、工具链和 Python 环境。
- Linux/macOS 的传统命令行安装方式：克隆 ESP-IDF 后运行
install.sh <target>，再在每个 shell 中加载export.sh。 - Windows：使用 EIM 或 ESP-IDF VS Code Extension 提供的 IDF Terminal，避免手工混用多个 Python/toolchain 环境。
# 传统 Linux/macOS 安装；应固定到项目要求的 ESP-IDF tag 或 release branch
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32c3
. ./export.sh
# 检查当前环境与支持的 target
idf.py --version
idf.py --list-targets
新建项目
# 从官方示例开始
cp -R "$IDF_PATH/examples/get-started/hello_world" my-project
cd my-project
# 第一次构建前选择芯片；该命令会清理 build/ 并重新生成配置
idf.py set-target esp32c3
idf.py menuconfig
idf.py build
# PORT 例如 /dev/ttyACM0、/dev/ttyUSB0 或 Windows COMx
idf.py -p PORT flash monitor
flash会先构建再写入；单独执行build便于尽早发现编译和配置问题。monitor退出快捷键为Ctrl+]。- target 变更会影响 toolchain、Kconfig、partition 和生成的构建产物；切换前先确认
sdkconfig.defaults的目标配置是否仍适用。
项目结构
my-project/
├── CMakeLists.txt # 顶层项目入口
├── sdkconfig.defaults # 可提交的默认 Kconfig 配置
├── sdkconfig # menuconfig 生成的当前配置
├── partitions.csv # 可选：分区表
├── main/
│ ├── CMakeLists.txt
│ └── main.c
├── components/ # 项目自有组件
├── managed_components/ # Component Manager 下载内容，通常不手工修改
├── dependencies.lock # 托管组件锁定文件
└── build/ # CMake/Ninja 生成目录，不提交
- 一个项目会构建 bootloader 与应用 firmware；分区表决定 app、NVS、OTA、文件系统等 flash 区域。
sdkconfig由idf.py menuconfig更新。团队应优先维护sdkconfig.defaults，必要时维护 target-specific defaults，例如sdkconfig.defaults.esp32c3。idf_component.yml描述组件元数据和托管依赖；dependencies.lock由 IDF Component Manager 更新，不应手工编辑。
常用命令
# 配置、构建与清理
idf.py menuconfig
idf.py build
idf.py reconfigure
idf.py fullclean
# 烧录与串口日志
idf.py -p PORT flash
idf.py -p PORT monitor
idf.py -p PORT flash monitor
# 仅烧录特定镜像
idf.py app-flash
idf.py bootloader-flash
# 查看构建尺寸与分区占用
idf.py size
idf.py size-components
idf.py size-files
配置与组件
- Kconfig：组件用
Kconfig暴露可配置选项；项目需要顶层菜单项时使用Kconfig.projbuild。 - CMake：每个 component 有自身的
CMakeLists.txt，通过idf_component_register(...)声明源文件、include 目录和依赖。 - Component Manager：第三方或复用组件通过
idf_component.yml声明版本约束；更新依赖后应审查dependencies.lock变化。 - 分区：量产、OTA 或文件系统需求应先确定
partitions.csv，再评估 app image size 与升级回滚策略。
FAQ
ESP-IDF vs MicroPython，怎么选？
- 选 ESP-IDF：需要长期维护的产品 firmware、精确的启动/内存/功耗控制、复杂 FreeRTOS 并发、原生驱动或协议栈集成、OTA/安全/量产配置，以及对时序、binary size 或性能有明确要求时。
- 选 MicroPython：需要快速验证传感器、GPIO、Wi-Fi、HTTP/MQTT 等设备行为，或希望用交互式 REPL 和 Python 快速迭代时。MicroPython ESP32 port 提供
machine、network等运行时模块，但不同 ESP SoC/board 的可用能力可能不同。 - 两者都需要：先以 MicroPython 验证硬件连线与产品交互，再将已稳定的需求按 ESP-IDF 的 C/C++ component 重写。不要把 MicroPython 脚本与 ESP-IDF application 视为同一 firmware 的可互换源码；它们的运行时、依赖与烧录镜像不同。
- 评估时不要只比较开发速度：同时比较目标芯片的 flash/RAM/PSRAM、实时性、功耗、异常恢复、第三方库、调试手段、团队语言经验和后续 OTA 运维需求。
切换 target 后为什么需要重新配置？
不同 SoC 的 Kconfig 选项、外设、ROM/bootloader 和 toolchain 约束不同。idf.py set-target <target> 会清理构建目录并重新生成配置，不能将旧 target 的 build/ 产物继续使用。
烧录时没有权限访问串口
确认 USB 数据线和实际设备节点；Linux 通常还需要将当前用户加入串口设备所属用户组，并重新登录后生效。不要以 root 常态化运行构建和烧录命令。
串口日志乱码
先确认 monitor baud rate 与 firmware 设置一致。若仅某块自制板异常，再检查晶振频率、复位/下载电路与 boot log 中的目标芯片识别结果。