本教程默认你是零基础新手，会尽量把每一步写清楚。你可以一边看一边操作，不需要先掌握完整理论。
一、教程简介
本教程讲解 FreeRTOS。教程按零基础方式编写，每一步都尽量说明“为什么做、在哪里点、做完看什么现象”。
【此处配图：FreeRTOS 整体流程图】
二、目录导航
- 前置准备
- 基础概念说明
- 详细步骤
- 参数设置说明
- 注意事项和避坑要点
- 新手易错点
- 常见问题 FAQ
- 总结
- 温馨提示
三、前置准备
你需要准备：
ext 能运行的 STM32 工程、CubeMX、Keil、串口日志
建议先创建一个单独的工程文件夹，把资料、代码、截图和调试日志都放进去。这样后面排查问题不会乱。
四、基础概念说明
在正式操作前，先记住三个原则：
- 先跑通最小功能：不要一开始就加很多复杂功能。
- 每一步都要验证现象：能编译、能下载、能输出日志，才继续下一步。
- 遇到错误先看日志：不要凭感觉改代码。
五、详细步骤
步骤 1：在 CubeMX 开启 FreeRTOS
操作流程： 打开 .ioc 文件，左侧点击 Middleware，点击 FREERTOS，Interface 选择 CMSIS_V1 或 CMSIS_V2。
需要填写或设置的参数： Heap 先选择 heap_4，Total heap size 新手可填 4096 或 8192。
做完以后看什么： 左侧 FREERTOS 变成绿色勾选状态。
避坑提醒： 内存小的芯片不要把 heap 填太大。
【此处配图：FreeRTOS - 在 CubeMX 开启 FreeRTOS 操作截图】
步骤 2：创建 LED 任务
操作流程： 进入 FREERTOS 的 Tasks and Queues，点击 Add。
需要填写或设置的参数： Task Name 填 ledTask，Priority 选 Normal，Stack Size 填 128 或 256。
做完以后看什么： 任务列表里出现 ledTask。
避坑提醒： 任务名不要用中文。
【此处配图：FreeRTOS - 创建 LED 任务 操作截图】
步骤 3：生成代码并编译
操作流程： 点击 GENERATE CODE，打开 Keil，点击 Build。
需要填写或设置的参数： 保持默认编译参数。
做完以后看什么： Keil 显示 0 Error。
避坑提醒： 如果生成代码后手写内容丢失，说明你写在了非 USER CODE 区域。
【此处配图：FreeRTOS - 生成代码并编译 操作截图】
步骤 4：在 LED 任务里写闪灯
操作流程： 打开 freertos.c，找到 StartLedTask 函数。
需要填写或设置的参数： while 循环里写 HAL_GPIO_TogglePin 和 osDelay(500)。
做完以后看什么： 下载后 LED 每 500ms 翻转。
避坑提醒： FreeRTOS 里不要用 HAL_Delay，优先用 osDelay。
【此处配图：FreeRTOS - 在 LED 任务里写闪灯 操作截图】
步骤 5：创建队列
操作流程： 在 Tasks and Queues 页面切换到 Queues，点击 Add。
需要填写或设置的参数： Queue Name 填 sensorQueue，Queue Size 填 8，Item Size 填 sizeof(uint16_t)。
做完以后看什么： 生成代码后能看到 osMessageQDef 或队列定义。
避坑提醒： Item Size 必须和你发送的数据类型一致。
【此处配图：FreeRTOS - 创建队列 操作截图】
步骤 6：发送队列数据
操作流程： 在传感器任务中调用 osMessagePut 或 xQueueSend。
需要填写或设置的参数： 每 1000ms 发送一次模拟温度值，例如 250。
做完以后看什么： 返回值为成功，日志任务能收到数据。
避坑提醒： 发送太快会导致队列满，要检查返回值。
【此处配图：FreeRTOS - 发送队列数据 操作截图】
步骤 7：创建二值信号量
操作流程： 在 CubeMX FREERTOS 的 Mutexes/Semaphores 页面点击 Add。
需要填写或设置的参数： Name 填 keySem，Type 选择 Binary Semaphore。
做完以后看什么： 生成代码后有 keySemHandle。
避坑提醒： 中断里释放信号量要用 FromISR 版本 API。
【此处配图：FreeRTOS - 创建二值信号量 操作截图】
步骤 8：观察任务运行
操作流程： 打开串口助手，波特率 115200，下载程序后复位开发板。
需要填写或设置的参数： 日志建议打印 LED task start、queue recv、key event。
做完以后看什么： 能看到多个任务交替输出，按键触发时打印 key event。
避坑提醒： 高优先级任务必须延时或阻塞，否则低优先级任务无法运行。
【此处配图：FreeRTOS - 观察任务运行 操作截图】
六、参数设置说明
常见参数建议：
| 参数 | 新手建议 |
|---|---|
| 串口波特率 | 115200 |
| 工程路径 | 使用英文路径 |
| 日志等级 | 调试阶段打开 INFO 和 ERROR |
| 超时时间 | 外设通信必须设置超时 |
七、注意事项和避坑要点
- 不要跳步骤：嵌入式调试最怕前面没跑通，后面越改越乱。
- 保留日志：每次失败都保存错误信息。
- 先确认硬件：接线、供电、下载器、串口工具都要检查。
- 不要把真实密钥提交到仓库：涉及云平台或 Wi-Fi 密码时尤其注意。
- 修改前先备份：新手建议每完成一小步就提交一次 Git。
八、新手易错点
- 工程路径包含中文或空格。
- 参数照抄但没有根据自己的芯片或开发板修改。
- 编译失败还继续下载。
- 串口线 TX/RX 接反。
- 忘记看开发板供电电压。
九、常见问题 FAQ
Q1：我完全没有基础，可以直接做吗？
可以。你只需要按步骤操作，每一步完成后确认现象。如果某一步失败，先不要继续。
Q2：教程里的参数和我的开发板不一样怎么办？
以你的开发板原理图和芯片手册为准。教程里的参数是示例，不是所有板子都完全相同。
Q3：遇到编译错误怎么办？
先看第一条 error，不要只看最后一行。很多后面的错误都是第一条错误引起的。
Q4：为什么要预留图片？
教程网页发布时可以把实际软件截图、接线图、波形图放到【此处配图】位置，读者会更容易跟着做。
十、总结
本教程的核心不是让你背概念，而是让你按步骤跑通一个真实小项目。新手学习嵌入式时，最重要的是 小步操作、及时验证、保留日志、逐项排查。
十一、温馨提示
如果你是第一次做 FreeRTOS，请不要追求一次成功。嵌入式学习的正确节奏是：做一步、看现象、保存记录、再做下一步。只要你能把失败现象记录清楚，问题就已经解决了一半。