ST-Forge 总体规划
ST-Forge 的目标不是再做一份零散的 STM32 笔记，而是做成一个可以长期生长的 STM32 学习工坊：新手能跟着点亮第一颗 LED，进阶者能理解时钟、总线、中断、DMA、文件系统和 RTOS，贡献者能围绕实验、模板、板卡适配和文档一起把项目打磨成社区级资源。
项目定位
ST-Forge 面向喜欢单片机、希望真正理解 STM32 的学习者。第一阶段聚焦 STM32F103C8T6 Blue Pill，使用开放工具链构建可复现的学习体验：
| 维度 | 规划 |
|---|---|
| 主控 | STM32F103C8T6，优先适配 Blue Pill |
| 主线 | C 语言、CMake、ARM GCC、OpenOCD、GDB、VS Code |
| 驱动层次 | 从寄存器意识出发，以 HAL 快速落地，关键章节补充寄存器视角 |
| 内容形态 | 文档教程、可编译工程、实验代码、板卡说明、排障手册 |
| 目标用户 | 初学者、Arduino 迁移者、C 语言学习者、嵌入式入门者、教学组织者 |
原则上，ST-Forge 不把学习者锁进单一 IDE。Keil/MDK、STM32CubeMX 等内容会作为对照材料和迁移知识出现；仓库主线以 CMake 工程和命令行可验证流程为准。
内容编排与改编原则
ST-Forge 的内容覆盖一条完整的 STM32 学习链：基础工具、C 语言硬件编程、GPIO、串口、定时器、DMA、ADC、DAC、IIC、SPI、CAN、USB、文件系统、RTOS 和综合实验。原则是“重新组织、而非逐字搬运”——每篇教程都围绕一个可验证的实验展开，目标是更适合 GitHub 文档站阅读、更适合复制运行、更适合社区维护。
主题到处理方式的编排如下：
| 主题方向 | ST-Forge 处理方式 |
|---|---|
| 入门路线、STM32 初识、工具准备 | 改写为学习路线、硬件清单、环境配置 |
| 寄存器工程、HAL、CubeMX、启动与 map | 以 CMake / VS Code 为主线，保留 MDK / CubeMX 作为对照说明 |
| 时钟树、delay、USART、GPIO | 作为第一批核心基础章节 |
| 按键、中断、串口、看门狗、定时器、OLED | 做成小实验阶梯，每章必须有硬件连接、代码、验证、排障 |
| LCD、RTC、低功耗、DMA、ADC、DAC、传感器 | 做成进阶外设模块，按 Blue Pill 可实现性筛选 |
| IIC、SPI、RS485、CAN、触摸、红外、温湿度、Flash、SD、FATFS | 做成总线与存储专题，明确额外模块和成本 |
| 汉字 / 图片显示、手写、输入法、DSP、IAP、USB | 作为高级专题或展示项目，避免过早进入主线 |
| RTOS、信号量、队列、综合实验 | 作为第二阶段收束项目 |
仓库产品形态
ST-Forge 应该同时是文档站和代码仓库。建议最终形成以下结构：
ST-Forge/
├── boards/ # 板卡定义、引脚图、调试器接线
├── documentations/ # VitePress 文档源
│ ├── tutorial/ # 正式教程
│ └── planning/ # 项目规划与路线图
├── examples/ # 每章可编译实验工程
├── firmware/ # 通用启动文件、链接脚本、HAL/CMSIS 封装
├── tools/ # 脚本、校验、生成器
├── site/ # VitePress 站点配置
├── project.config.ts # 站点项目信息
└── README.md # GitHub 门面examples/ 是明星仓库的关键。文档能讲清楚，示例能跑起来，学习者才会愿意 star、fork、提 issue。
课程路线图
ST-Forge 的课程先分成两条线：基础篇先落地，实战篇先规划。
基础篇服务当前阶段，目标是让学习者从零跑通 Blue Pill 的完整开发闭环；实战篇服务未来阶段，目标是把已经学到的外设能力组合成可以展示、可以扩展的小作品。
| 篇章 | 阶段定位 | 当前策略 |
|---|---|---|
| 基础篇 | v0.1 主线 | 立即落地，章节、示例工程、排障一起做 |
| 外设篇 | v0.2-v0.3 主线 | 跟随基础篇逐步扩展，不急于铺满 |
| 实战篇 | v0.4+ 主线 | 先做远期规划，等基础篇稳定后选择首批项目 |
| 排障篇 | 持续补充 | 从真实学习过程和 issue 中沉淀 |
| 模板篇 | 持续补充 | 服务示例工程复用和社区贡献 |
基础篇 v0.1：从零跑通一块 Blue Pill
基础篇是 ST-Forge 的第一根主梁。它不追求炫技，而是追求小白能跟着走、每章都能验证、每个关键问题都能解释清楚。
基础篇的完成标准：
- 用户知道该买什么硬件、怎么接线、怎么判断板子和调试器正常。
- 用户能在 Windows 或 WSL/Linux 下完成工具链配置。
- 用户能编译、烧录、调试一个 CMake 工程。
- 用户理解
main.c、启动文件、链接脚本、HAL/CMSIS、CMake 之间的关系。 - 用户能独立完成 GPIO、串口、中断、定时器这几类最常用能力。
- 用户遇到烧录失败、串口乱码、HardFault、时钟异常时，有基本排查路径。
计划章节如下：
| 编号 | 章节 | 交付物 |
|---|---|---|
| 0.0 | 学习路线与硬件清单 | Blue Pill、ST-Link、USB-TTL、杜邦线、面包板清单 |
| 0.1 | 板卡认识与接线 | 供电、BOOT0/BOOT1、SWD 接线、常见假板风险 |
| 0.2 | Windows 环境配置 | ARM GCC、CMake、OpenOCD、Git、VS Code |
| 0.3 | WSL/Linux 环境配置 | gcc-arm-none-eabi、openocd、USB/udev 注意事项 |
| 0.4 | 第一次编译 | CMake configure/build、.elf/.bin/.hex 产物解释 |
| 0.5 | 第一次烧录 | OpenOCD 烧录、ST-Link 连接验证、失败排查 |
| 0.6 | 第一次调试 | GDB、断点、单步、变量、寄存器观察 |
基础篇 v0.1：芯片与工程基本功
目标：学习者知道代码如何从复位进入 main，知道外设为什么要开时钟，知道寄存器、HAL 和 C 代码之间的关系。
计划章节：
| 编号 | 章节 | 核心实验 |
|---|---|---|
| 1.1 | Cortex-M3 与 STM32F103 内存映射 | 手算 GPIO 寄存器地址 |
| 1.2 | 启动文件、链接脚本与 map 文件 | 看懂 Flash/RAM 占用 |
| 1.3 | CMake 工程结构 | 新建最小工程 |
| 1.4 | C 语言硬件基础 | 位操作、宏、结构体、指针、volatile |
| 1.5 | HAL 与寄存器的关系 | 用 GPIO 例子对照 HAL 调用和寄存器变化 |
| 1.6 | 时钟树 | HSI/HSE/PLL 与 72 MHz 配置 |
| 1.7 | map 文件与内存占用 | 从构建产物反推代码进入芯片的方式 |
基础篇 v0.1：最小外设能力
目标：从“能点灯”走到“能写一个小型交互程序”。这一段是基础篇最重要的实操部分，每章都必须配套示例工程。
| 编号 | 章节 | 核心实验 |
|---|---|---|
| 2.1 | GPIO 输出 | 板载 LED 闪烁 |
| 2.2 | GPIO 输入 | 按键读取、上拉下拉、软件消抖 |
| 2.3 | SysTick 与 delay | 微秒/毫秒延时、阻塞式延时的代价 |
| 2.4 | USART 输出 | printf、串口工具、乱码排查 |
| 2.5 | USART 输入 | 回环、简单命令解析 |
| 2.6 | EXTI 外部中断 | 按键中断、NVIC、优先级 |
| 2.7 | 基本定时器 | 周期中断、非阻塞闪烁 |
| 2.8 | PWM 入门 | 呼吸灯、占空比调节 |
| 2.9 | 调试与故障分析 | 断点、单步、HardFault、看门狗式排查思路 |
基础篇收官项目：Blue Pill Mini Console
基础篇最后用一个不依赖额外模块的小项目收束。它要足够简单，保证新手能完成；也要足够完整，让学习者感受到自己真的写出了一个小设备。
项目功能：
| 功能 | 涉及知识 |
|---|---|
串口命令 led on/off/toggle | USART、命令解析、GPIO 输出 |
串口命令 blink 100/500/1000 | 定时器、状态机、非阻塞逻辑 |
串口命令 pwm 0-100 | PWM、参数解析、占空比 |
| 按键切换运行状态 | GPIO 输入、消抖、EXTI |
| 串口打印当前状态 | printf、结构化状态输出 |
| 调试观察变量变化 | GDB、断点、watch、寄存器 |
项目交付物：
examples/99_bluepill_mini_console示例工程。- 一篇项目教程，按“需求 -> 设计 -> 实现 -> 调试 -> 扩展”组织。
- 一份命令清单和预期串口输出。
- 一份常见问题排障表。
外设篇 v0.2-v0.3：基础之外的能力扩展
外设篇不急着在第一阶段铺满。它的作用是为实战篇准备零件库，让学习者逐渐掌握更多传感器、总线、存储和通信能力。
| 模块 | 章节方向 | 实验 |
|---|---|---|
| ADC | 单通道、多通道、采样时间 | 电位器采样、电池电压测量 |
| DMA | 内存搬运、外设搬运 | USART DMA、ADC DMA |
| I2C | 24C02、OLED | 参数保存、屏幕显示 |
| SPI | W25Q64、OLED/TFT | Flash 读写、图片显示 |
| RTC | 时间、备份寄存器 | 小时钟、掉电时间保持 |
| 低功耗 | Sleep/Stop/Standby | 待机唤醒实验 |
| 1-Wire | DS18B20 | 温度采集 |
| 单总线时序 | DHT11 | 温湿度采集 |
| 红外 | NEC 协议 | 遥控器解码 |
| RS485/CAN | 工业通信入门 | 多板通信 |
| Flash 与参数区 | 内部 Flash 擦写 | 保存配置 |
| Bootloader/IAP | 固件升级 | 串口升级应用 |
| FATFS | SD 卡与文件系统 | 数据记录器 |
| USB | CDC、MSC | 虚拟串口、U 盘设备 |
| RTOS | 任务、队列、信号量、定时器 | 多任务采集与显示 |
实战篇远期规划：把知识变成作品
实战篇先不作为近期交付压力，而是作为远期项目地图。等基础篇稳定后，再从中选择 2-3 个成本低、效果直观、资料好维护的项目进入实现。
候选项目：
| 项目 | 核心看点 | 依赖知识 | 优先级 |
|---|---|---|---|
| OLED 小仪表盘 | 有屏幕、有页面、容易展示 | I2C/SPI、字体、按键菜单 | 高 |
| 桌面环境监测站 | 温湿度、光照、电压集中显示 | DHT11/DS18B20、ADC、OLED | 高 |
| 迷你数据记录仪 | 真正有“产品感”的小设备 | RTC、SD、FATFS、CSV | 高 |
| 红外遥控学习器 | 协议解析有趣，现象直观 | 定时器输入捕获、状态机 | 中 |
| PWM 灯光/舵机控制器 | 适合演示定时器能力 | PWM、按键、串口调参 | 中 |
| USB 工具棒 | 和电脑交互，传播性强 | USB CDC/MSC、Flash | 中 |
| 简易 Bootloader | 工程深度强 | Flash、IAP、链接脚本、启动跳转 | 中 |
| RTOS Sensor Hub | 作为高级收束项目 | RTOS、队列、互斥、定时器 | 低 |
实战篇的原则：
- 优先选择低成本、好买、好接线的模块。
- 每个项目都必须能拍图、录屏或保存串口日志，方便 README 展示。
- 项目教程不堆外设，而是讲清楚需求拆分、模块边界、调试过程和扩展方向。
- 如果某个项目需要复杂硬件，必须提供简化版本。
文档写作标准
每一篇教程固定采用同一套结构：
- 本章目标：读完能做什么。
- 硬件准备：模块、引脚、接线图、注意事项。
- 概念解释：只讲完成实验必须理解的内容。
- 工程改动：新增文件、关键代码、CMake 变化。
- 编译烧录：命令、预期输出、产物位置。
- 现象验证：用户应该看到什么。
- 常见问题：错误日志、原因、修复。
- 延伸练习：一到三个可完成的小改造。
文风要保持“友好但准确”：少一点术语堆砌，多一点工程现场感；但所有寄存器、时钟、引脚、命令都必须可核对。
示例工程标准
每个实验工程应满足：
| 标准 | 要求 |
|---|---|
| 可编译 | cmake --build 必须通过 |
| 可烧录 | OpenOCD 配置明确 |
| 可调试 | VS Code launch 配置或 GDB 命令明确 |
| 可复用 | 公共启动文件、链接脚本、HAL/CMSIS 不重复散落 |
| 可验证 | 文档中说明预期串口输出、LED 状态或测量结果 |
建议先建立一个 examples/00_blink_cmake 黄金模板。后续所有章节从模板复制演进，避免每篇教程重新发明工程结构。
社区与传播规划
要成为明星仓库，除了内容完整，还需要让人愿意参与。
| 方向 | 规划 |
|---|---|
| GitHub 门面 | README 写清楚愿景、快速开始、路线图、贡献方式 |
| Issue 模板 | 区分环境问题、教程错误、板卡适配、功能建议 |
| PR 规则 | 文档、示例、板卡三类贡献路径 |
| Good First Issue | 从错别字、截图补充、模块验证、排障条目开始 |
| 版本路线 | v0.1 跑通环境，v0.2 基础外设，v0.3 总线模块，v1.0 完整课程 |
| 展示材料 | 每个明星实验保留图片/GIF/串口日志，方便 README 展示 |
第一批里程碑
各里程碑的可勾选行动项已展开到行动路线图，下面是各里程碑的目标与完成标准。
Milestone 1：基础篇骨架
- 完成 README 项目门面。
- 完成基础篇目录设计。
- 统一“基础篇 / 外设篇 / 实战篇 / 排障篇 / 模板篇”的站点结构。
- 明确 Blue Pill 硬件清单、供电方式、启动模式、ST-Link 接线。
- 确定基础篇每章的示例工程命名规则。
Milestone 2：黄金模板
- 新增
examples/00_blink_cmake。 - 建立公共
firmware/或templates/结构。 - 支持
cmake configure/build/flash/debug基础闭环。 - 文档覆盖 Windows 与 WSL/Linux。
Milestone 3：基础篇核心章节
- GPIO 输出、GPIO 输入、SysTick、USART、EXTI、基本定时器、PWM。
- 每章配套示例工程。
- 每章增加常见错误和排障。
- 每章都能从“现象验证”回到“工程结构”和“芯片机制”。
Milestone 4：基础篇收官项目
- 完成
Blue Pill Mini Console。 - 串口命令、GPIO、按键、中断、定时器、PWM 串成一个完整工程。
- 增加调试章节：如何用断点和变量观察理解项目运行。
- README 增加基础篇完成后的学习成果说明。
Milestone 5：实战篇首批项目选择
- 从 OLED 小仪表盘、桌面环境监测站、迷你数据记录仪中选择首批项目。
- 建立外设模块购买清单与引脚占用表。
- 整理贡献指南，开始面向社区征集验证反馈。
当前决策
- ST-Forge 主线采用 CMake + ARM GCC + OpenOCD + GDB。
- 基础篇作为 v0.1 的近期目标，先保证小白能从零跑通 Blue Pill。
- 教程内容围绕可验证的实验重新组织，强调适合工程实践与社区维护。
- HAL 作为第一阶段落地 API，关键章节补充寄存器视角。
- Blue Pill 是第一目标板卡，所有实验先评估是否能在 Blue Pill 上低成本复现。
- 实战篇先做远期规划，不抢基础篇的落地节奏。
- 文档和示例工程同等重要；没有可运行工程的教程不算完成。
近期行动清单
详细的、可勾选的行动项已拆解到行动路线图，按里程碑组织。当前最该动手的三件事：
- [ ] 新增
examples/00_blink_cmake黄金模板与firmware/公共底座，跑通编译烧录调试闭环（Win + WSL）。 - [ ] 落地八段式章节模板，后续所有章节按模板扩写。
- [ ] 补齐 Blue Pill 板卡文档：引脚、供电、启动模式、ST-Link 接线。
完整进度见 roadmap.md。
- [ ] 为
Blue Pill Mini Console写需求草案和命令清单。