phonerail/firmware/HANDOFF.md

交接

更新：2026-09-06　完成任务包 A1（工程骨架）

一句话现状

firmware/ 骨架立起来了：同一份 main/ 源码在宿主机（cygwin gcc + CTest + Unity） 和 ESP-IDF v5.4 / esp32s3 两个目标下都编得过，两条验收命令都是绿的。

下一步

A2：HAL 接口（i2c / gpio / pwm / time）+ sim 实现。 新增的 .c 要同时登记到 main/CMakeLists.txt 的 SRCS 和 host/CMakeLists.txt 的 PHONERAIL_CORE_SRCS（两处，漏一处就是「宿主机绿了但上板编不过」）。

本次新增/修改的文件

• CMakeLists.txt、sdkconfig.defaults — IDF 工程根，目标 esp32s3 / 8 MB flash
• main/phonerail.h、main/version.c — 版本号与通道数，两个目标共享
• main/app_main.c — ESP 专用入口（宿主机构建不含此文件）
• main/CMakeLists.txt — IDF main 组件
• host/CMakeLists.txt — 宿主机根工程：phonerail_core + unity + test/test_*.c 自动成 ctest
• host/test.sh — 宿主机验收一条命令
• build_idf.ps1 — 目标验收一条命令（钉死 v5.4、关 ccache）
• test/test_version.c — A1 的假测试（A2 起有真逻辑后可删）
• third_party/unity/ — 从 IDF v5.4 原样复制的 Unity（上板测试同一套框架）
• ../固件开发计划.md §10 — 钉死了 IDF 版本与测试框架两个待定项

验收命令与结果

$ bash host/test.sh
100% tests passed, 0 tests failed out of 1

$ .\build_idf.ps1          # PowerShell
phonerail.bin binary size 0x32520 bytes. ... 0xcdae0 bytes (80%) free.
Project build complete.

踩到的坑（只写会再犯的）

• 宿主机必须用 cygwin 那套 cmake/ctest/gcc（/c/cygwin64/bin/）。 Windows 版 CMake（C:\Program Files\CMake）配 cygwin gcc 会认错平台。
• cygwin cmake 只认 /cygdrive/...：喂它 D:/... 会报 Found relative path while evaluating include directories。 所以 host/test.sh 先 cd 再全用相对路径，不传绝对路径。 同理 -DCMAKE_C_COMPILER=/c/... 会被 Git Bash 的路径转换搞坏，改用 export CC=gcc。
• IDF_CCACHE_ENABLE=0：开着 ccache 时 IDF 自带的 esp_lcd_panel_rgb.c 编出过一次编译器 segfault（ICE），关掉就过。已写进 build_idf.ps1。
• PowerShell 5.1 + $ErrorActionPreference="Stop" 会把 export.ps1 的正常 stderr 当成终止错误（"Activating ESP-IDF 5.4" 就报红）。build_idf.ps1 已去掉它，改用 exit $LASTEXITCODE。
• 机器上有四个 IDF（v5.3.1 / v5.4 / v5.5 / v5.5.1 / v6.0-rc1）。 PATH 上的是 D:\Users\35138\esp\v5.4，本工程就钉这个。
• git 仓库已建（D:\DCDC，分支 main，初始提交 7a85df9）。 .gitattributes 默认 * -text（不重写行尾），只有 *.sh 强制 LF。 build/、host/build/、sdkconfig 已被忽略，别硬 git add -f 进去。