学习笔记 · Obsidian
ESP-IDF 工程、编译和烧录
先走完整个开发闭环
源文件经过预处理、编译与链接得到目标程序，再写入 Flash，由芯片启动执行。Mac 上编译 C 练习是本机编译，ESP-IDF 构建固件则使用目标芯片工具链。二者验证的是不同环境。
main/*.c → 构建系统与组件 → ELF / 固件镜像 → flash → 芯片运行 → monitor 日志版本口径
这套笔记的 ESP-IDF API 固定引用 v5.5.1 / esp32s3，目的是让文档可复查，不声称它是当前最新或生产选型。首次学习可把它作为候选环境。
2026-09-10 核对结果：
| 来源 | 查到什么 | 怎样使用 |
|---|---|---|
| M5 CoreS3 BSP 教程 | 示例组合为 IDF v5.4.1、BSP ^3.0.0 | 理解流程；勿与新版代码无差别混用 |
| 组件注册表 | CoreS3 BSP 展示版本 4.1.0 | 新项目先看此版本 manifest 和例子 |
| 对应仓库 manifest | BSP 4.1.0 声明 idf >=5.4 | v5.5.1 满足直接约束；不等于完整依赖解析和实机验证通过 |
来源：M5 BSP 教程、BSP 4.1.0 注册表、BSP manifest。仓库 master 会变化，开始工程时记录 commit。
进入 BSP 阶段后，应保存 idf_component.yml、dependencies.lock、必要的 sdkconfig.defaults 及实际 IDF 版本。不要手改 managed_components 解决版本问题。
Mac 的第一条实验链路
先按 官方 Linux/macOS 安装说明 安装和激活选定版本。本文不预设本机已安装 SDK。
在已激活 ESP-IDF 的终端、一个独立且不存在同名工程的学习目录中：
idf.py --version
cp -R "$IDF_PATH/examples/get-started/hello_world" ./cores3-hello
cd cores3-hello
idf.py set-target esp32s3
idf.py build找到设备真实串口后，再执行以下两步；/dev/cu.usbmodemXXXX 是占位符，必须替换：
idf.py -p /dev/cu.usbmodemXXXX flash
idf.py -p /dev/cu.usbmodemXXXX monitor退出 monitor 通常使用 Ctrl+]。Hello World 不初始化 LCD，屏幕没有应用画面不代表这个串口实验失败。烧录会改变设备当前固件；先记录现有固件来源与恢复方式。官方构建与烧录流程
先认四类文件
| 文件 | 负责什么 |
|---|---|
工程根 CMakeLists.txt | 接入 ESP-IDF 构建体系并命名工程 |
main/CMakeLists.txt | 声明本组件源文件和依赖 |
main/*.c | 应用入口和逻辑 |
sdkconfig / sdkconfig.defaults | 实际配置 / 可复现配置的默认项 |
app_main 中创建周期任务后，让任务通过阻塞或延时等待下一次工作；不要写一个不让出 CPU 的空转循环。普通创建的任务函数与 app_main 的生命周期规则不同，后者可以返回。IDF FreeRTOS
失败时按证据拆分
| 现象 | 优先检查 |
|---|---|
找不到 idf.py | 当前终端是否激活正确 SDK |
| 编译报类型、头文件错误 | 芯片目标、依赖和 API 文档版本是否一致 |
| 串口不出现 | 数据线、接口、设备供电与下载模式 |
| 能烧录但看不到日志 | 实际端口、控制台配置、设备是否复位、端口是否被占用 |
| 运行后重启 | 保存第一段错误与 backtrace，区分断电、看门狗、非法访问 |
验收：记录构建成功、烧录成功、启动日志三个结果；只有三者都通过才算完成首次板卡运行。当前资料整理阶段未执行安装或烧录。