STM32F103+RT-Thread Nano+Finsh组件移植避坑指南（Keil环境实测）

STM32F103+RT-Thread Nano+Finsh组件移植避坑指南（Keil环境实测）

最近在帮几个朋友调试他们的STM32项目，发现不少人在从裸机转向RTOS时，第一个拦路虎往往不是RTOS本身，而是如何把它顺利“搬”到自己的板子上。尤其是RT-Thread Nano，以其轻量、易上手著称，但真在Keil环境下动手移植，特别是想加上Finsh这个命令行“神器”时，各种编译错误、链接问题、串口不打印的坑就接踵而至。这篇文章，我就结合自己最近在STM32F103C8T6（也就是大家常说的“蓝色小药丸”）上的实测经历，把整个移植流程掰开揉碎，重点聊聊那些文档里可能一笔带过，但实际开发中会让你卡壳半天的“坑点”。无论你是刚接触RT-Thread的嵌入式新手，还是想快速在项目中引入实时内核和调试工具的中级开发者，希望这份避坑指南能让你少走弯路。

1. 工程准备与环境搭建：从零开始的正确姿势

移植的第一步，不是急着往工程里塞代码，而是把地基打好。很多初学者容易忽视环境配置的细节，导致后续问题层出不穷。

1.1 Keil MDK与RT-Thread Nano Pack安装要点

首先确保你使用的是较新版本的Keil MDK（如V5.36及以上），对ARM Compiler 6（AC6）的支持更完善。RT-Thread Nano通常以Pack包形式提供，从官网下载后直接双击安装即可。这里有个关键细节：安装完成后，务必在Keil的Pack Installer窗口中确认RT-Thread Nano的包已被正确识别并启用。我遇到过因为Keil版本过旧或Pack安装路径包含中文，导致后续添加软件包失败的案例。

注意：如果你的项目之前是纯裸机工程，建议先备份。移植过程会修改工程结构，备份可以让你在遇到问题时快速回退。

1.2 创建或准备一个健康的裸机工程

一个稳定、能正常编译运行的裸机工程是移植的基石。至少需要包含：

• 正确的芯片型号支持包（Device Family Pack）。
• 系统时钟初始化（通常使用标准库或HAL库的SystemInit()）。
• 一个简单的GPIO控制LED的代码，用于后续验证RTOS线程是否正常运行。

检查你的工程是否已经正确处理了中断向量表。对于STM32F103，启动文件（如startup_stm32f10x_md.s）是必须的。在Keil中，它通常位于Device分组下。

2. 内核移植：避开那些“看似简单”的陷阱

将RT-Thread Nano内核添加到工程中，官方文档的步骤看起来清晰，但实操时有几个地方极易出错。

2.1 添加Nano包与源码文件

在Keil工程中，通过Manage Run-Time Environment（RTE）窗口添加RT-Thread Nano。勾选Core和Device Drivers下的UART（为后续Finsh做准备）。Keil会自动添加一组核心源文件，如rtthread.c、board.c等。

第一个大坑：中断向量冲突。 RT-Thread Nano接管了PendSV_Handler（用于任务切换）和SysTick_Handler（系统时钟节拍）。因此，你必须手动删除（或注释掉）工程中stm32f10x_it.c文件里的这两个函数实现。否则，链接时会报重复定义错误。同样，HardFault_Handler有时也需要处理，但通常保留用户自定义的调试版本更有用。

2.2 系统时钟节拍（SysTick）配置

这是移植的核心之一。编译工程，你很可能会遇到第一个编译错误：

#error "TODO 1: OS Tick Configuration."

这个错误提示你需要在board.c文件的rt_hw_board_init()函数中配置系统时钟节拍。解决方法如下：

1. 首先，在board.c文件顶部添加芯片头文件：

   #include "stm32f10x.h"
   

2. 找到rt_hw_board_init()函数，注释掉产生错误的#error行。
3. 在该位置添加SysTick初始化：

   SysTick_Config(SystemCoreClock / RT_TICK_PER_SECOND);
   

   这里的RT_TICK_PER_SECOND在rtconfig.h中定义，默认是100，即每秒100个tick，每个tick 10ms。你可以根据需求调整，值越大，时间精度越高，但系统开销也略增。
4. 实现SysTick中断服务函数。在board.c中添加以下函数：

   void SysTick_Handler(void)
   {
       rt_interrupt_enter();
       rt_tick_increase();
       rt_interrupt_leave();
   }
   

5. 关键步骤：添加了上面的SysTick_Handler后，必须去stm32f10x_it.c中删除或注释掉原有的SysTick_Handler函数体。否则又是重