esp-forge

esp-forge 是一套围绕 ESP32-S3 和 ESP-IDF 编写的学习笔记与实验。它不打算再做一份 API 手册，而是从一个能运行的小工程出发，逐步回答这些更实际的问题：工程为什么这样组织，程序如何启动，任务和内存出了问题该看哪里，以及仿真结果和真板结果之间有什么差别。

项目还在早期建设中。目前只有环境搭建和第一个工程，后续内容会边学习、边实验、边整理。README 只描述仓库中已经存在的内容；完整路线不会被当作完成清单展示。

现在有什么

esp-forge/
├── code/
│   └── 00_bootstrap/       第一个 ESP-IDF 工程
├── document/
│   └── 00-bootstrap/       环境、Hello World、烧录与 USB 透传笔记
└── idf/                    本地放置 ESP-IDF（SDK 本身不提交）

建议按下面的顺序阅读：

1. 搭建环境与创建工程
2. 理解 Hello World 工程
3. 编译、烧录与 WSL2 USB 透传

对应的代码在 code/00_bootstrap。

构建第一个工程

仓库当前以 ESP-IDF v6.0.2、目标芯片 esp32s3 为基线。先安装 ESP-IDF；可以把 SDK 放在 idf/esp-idf，也可以使用你自己的安装位置。

如果 SDK 位于仓库内：

git clone --recursive https://github.com/espressif/esp-idf.git idf/esp-idf
cd idf/esp-idf
git checkout v6.0.2
./install.sh esp32s3
cd ../..

激活环境并构建：

. idf/esp-idf/export.sh
cd code/00_bootstrap
idf.py set-target esp32s3
idf.py build

连接开发板后，可继续烧录并查看串口输出：

idf.py -p /dev/ttyUSB0 flash monitor

串口名不一定是 /dev/ttyUSB0。如果你在 WSL2 中开发，还需要先从 Windows 侧把 USB 设备透传进 WSL，具体步骤见烧录与 USB 透传笔记。

这条路线会往哪里走

后续计划围绕以下主题展开：

• ESP-IDF 的工程结构、配置系统和构建产物；
• 启动链、内存布局、异常与调试；
• FreeRTOS SMP、任务同步和跨核问题；
• GPIO、UART、I2C、SPI 等常用外设；
• Wi-Fi、BLE、USB、NVS 和 OTA；
• 低功耗、故障恢复和长期运行。

每个主题都尽量保留同一条学习路径：先完成最小功能，再观察系统状态，主动制造一个错误，最后只下钻到足以解释现象的实现细节。目标是既会调用 API，也能在复制示例不再奏效时继续排查。

验证边界

仓库会用 Host 测试、QEMU、Wokwi 和真板，但不会混用它们的结论。Host 适合测试纯逻辑，QEMU 和 Wokwi 适合可重复的流程或交互；Wi-Fi/BLE 射频、USB 兼容性、PSRAM 时序、引脚与供电、睡眠唤醒和功耗等结论仍以真板为准。

Secure Boot、Flash Encryption 和 eFuse 涉及不可逆配置。相关实验不会在唯一一块开发板上直接执行，真实烧写只应使用专门准备、可以牺牲的测试板。

范围

主线只维护 ESP32-S3 + ESP-IDF。Arduino、PlatformIO 和 MicroPython 最多用于迁移时的对照；其他 ESP32 型号、手机 App、云平台、通用 GUI 与重写无线协议栈不在当前范围内。

License

MIT