本文是 「从 0 到 1 带你打电赛 · 小车电控篇」 系列（共 12 篇）第 11 篇。

1. 第1篇 · 拿奖逻辑：把比赛拆成小目标
2. 第2篇 · 赛题进化史与押题
3. 第3篇 · 整车搭建与代码框架
4. 第4篇 · 电机驱动与电源地基
5. 第5篇 · 感知：灰度/电磁/编码器/IMU
6. 第6篇 · PID 入门：搞懂 P/I/D
7. 第7篇 · PID 进阶：串级+工程补丁
8. 第8篇 · PID 调参实战(核心)
9. 第9篇 · 进阶控制：几时该上
10. 第10篇 · K230 视觉与通信协议
11. 第11篇 · 状态机与整车软件（本篇）
12. 第12篇 · 现场作战+避坑+开源

电赛小车系列前面十篇，我们把电控的零件一个个磨出来了：电机能听话转、传感器看得见路、PID 能把速度和方向调稳、视觉和主控也能对上话。但这些都还只是”零件”。这一篇，我们要做的是把所有零件焊成一台真正能在赛道上跑的车。

你会发现一个有意思的现象：很多队伍每个模块单测都好好的——电机转得欢、灰度读得准、PID 波形漂亮——可一旦合到一起跑整车，就开始抽风：要么卡死不动，要么时灵时不灵，要么过个十字就冲出去了。问题几乎都不在某个模块本身，而在”怎么把它们组织起来、谁先跑谁后跑、出了岔子怎么兜底”。这就是整车软件架构要解决的事。

这一篇我们讲清四件事：分层（代码怎么摆放）、调度（谁在什么时候跑）、控制环时序（一拍里按什么顺序干活）、状态机（整车行为怎么管），最后再钉一遍贯穿全系列的保护逻辑和那条”机械定上限、软件定下限”的硬道理。吃透这几件事，你的车就从”一堆能动的零件”变成”一台能比赛的车”。

一、分层架构：让你的算法”换芯片不换脑子”

先讲个大白话比喻。写整车软件像点外卖：

这正是逐飞、恩智浦那套智能车开源库多年沉淀下来的标准做法。把代码分成四层，上层依赖下层、下层不知道上层的存在：

以逐飞 SeekFree 库为例，它的真实分层是这样的：

中间件层（PID、滤波、协议、元素识别）这些纯算法，本质上和芯片没有任何关系——它们只是数学，搬到任何平台上都一样跑。

一条必须刻进脑子的铁律

这条铁律还是用打比方理解最快：

为什么值得花这个力气分层？ 因为它直接决定了你前面那些功夫能不能”白嫖”过来。整车搭建那一篇讲过”STM32 练手、MSPM0 比赛”的策略，分层就是这套策略能成立的根。看一组实打实的证据：同一套逐飞库，社区已经移植到了 RT1064、英飞凌 TC264、STC32G144K，甚至 2025 年 TI 板电赛用的 MSPM0G3507。这些版本的 App 层和算法层几乎一字不改，差异全部集中在底层驱动。

想找范本直接抄结构的，推荐 Sakuramdd/SeekFree_RT1064_Opensource_Library，标准三层加上 code 目录（image / control / init），是研究分层与解耦最干净的样本。STM32 与 MSPM0 之间具体怎么对应 API、平移时要注意什么，整车搭建那一篇已经给过对照心法，这里不展开。

二、调度：电赛首选”前后台裸机”，别动不动就上 RTOS

代码摆好了，下一个问题是：这么多任务——读传感器、跑 PID、刷屏、收视觉数据——谁在什么时候跑？这叫调度。常见的有三档，我们从简单到复杂排一下。

第一档：前后台裸机（电赛首选）

这是最常见、最可预测的方案，也是绝大多数电赛车的选择。结构极简：

把这套结构画出来就是：

第二档：时间片轮询

如果你有好几个不同周期的任务（控制环 5ms、读视觉 20ms、刷屏 100ms），可以用一个简单的时间片调度器：用一个 1ms 的定时器统一递减计时，到点就给任务打个”该跑了”的标记，主循环看到标记再去执行。

// 时间片轮询调度器：一个 1ms 的 tick 管多周期任务
typedef struct { uint16_t period, timer; uint8_t run; void(*task)(void); } Task_t;

Task_t tasks[] = {
    {5,   5,   0, Control_Loop},  // 5ms：  控制环
    {20,  20,  0, Read_Vision},   // 20ms： 收视觉
    {100, 100, 0, Update_OLED},   // 100ms：刷屏
};
#define N (sizeof(tasks) / sizeof(tasks[0]))

void SysTick_Handler(void) {          // 1ms tick
    for (int i = 0; i < N; i++) {
        if (tasks[i].timer == 0) { tasks[i].timer = tasks[i].period; tasks[i].run = 1; }
        else tasks[i].timer--;
    }
}

int main(void) {
    Init();
    while (1)
        for (int i = 0; i < N; i++)
            if (tasks[i].run) { tasks[i].run = 0; tasks[i].task(); }
}

这其实是前后台的”加强版”，介于裸机和 RTOS 之间——能管多个不同周期的任务，但仍然透明可控、没有调度器的黑盒。

第三档：RTOS（FreeRTOS / RT-Thread）

只有当任务真的多、真的需要并发的时候才上 RTOS。它的代价不小：

电赛如果真要上 RTOS，主流就是 FreeRTOS 和 RT-Thread 这两个。

那到底该不该上 RTOS？

更具体地说，宁可用周期性裸机也不上 RTOS 的理由有三条，都很实在：

• 确定性：定时器中断直接管任务，没有 RTOS 那套调度算法和优先级反转，固定周期任务给你严格的时序保证，最坏执行时间也好分析。
• 低开销：省掉内核那几 KB 的 ROM/RAM，省掉每个任务的控制块（TCB）。
• 易验证：任务少（三五个）时，状态机比多线程透明得多，不会有死锁、没有同步 bug。

记住一句话：RTOS 是给”任务多到管不过来”准备的解药，不是给整车软件撑场面的装饰品。

三、控制环时序：5ms 一拍，按死顺序干活

调度定好了，现在聚焦最核心的那个”前台”——控制环。它跑在定时器中断里，是整车的心跳。

为什么是 5ms（也就是 200Hz）？这是智能车社区多年试出来的甜点：够快，能保证控制平滑；又不至于太快，给中断里的计算留足时间。背后有个定量依据——采样定理（Nyquist）：采样频率要大于被控信号变化频率的 2 倍，才不会”漏看”信号的变化。小车的动态没那么快，5ms 一拍绰绰有余。

STM32 上配一个 5ms 中断很简单：在 72MHz 主频下，预分频 PSC = 72（把计数时钟降到 1MHz，即 1µs 一格）、重装载 ARR = 5000（数 5000 格就是 5ms），就是精确的 5ms。

一拍里的标准流程

中断一进来，按这个顺序走，一步都不能乱：

落成代码骨架就是这样（前后台架构里的”前台”）：

// PIT / TIM 5ms 中断 —— 固定周期控制环（前台）
void TIM3_IRQHandler(void) {
    if (TIM_GetITStatus(TIM3, TIM_IT_Update)) {
        TIM_ClearITPendingBit(TIM3, TIM_IT_Update);

        // 1) 采集：读编码器测速，读完立刻清零
        int16_t el = Read_Encoder(L); Clear_Encoder(L);
        int16_t er = Read_Encoder(R); Clear_Encoder(R);
        IMU_Read(&gyro, &acc);

        // 2) 融合：互补滤波出姿态角
        float ang = Complementary_Filter(acc, gyro, 0.005f);

        // 3) 串级 PID：外环速度 → 内环转向
        int16_t ps = Speed_PI(target, (el + er) / 2);   // 外环：速度
        int16_t pt = Turn_PD(line_err, gyro.z);         // 内环：转向

        // 4) 输出：差速 + 限幅后写 PWM
        Set_Motor(LIMIT(ps - pt, -7200, 7200),
                  LIMIT(ps + pt, -7200, 7200));

        // 5) 保护：视觉超时则降级，绝不盲冲
        if (++vision_timeout > VTO) Set_Motor_Safe();
    }
}

内环必须比外环快

讲串级 PID 时埋过一个伏笔，这里再钉一遍：

所以控制环里的铁律是：内环周期 ≤ 外环周期，且内环先调稳。外环的输出是内环的目标，内环都晃晃悠悠，外环再准也没用。具体的调参顺序（先内后外、先 P 后 I 再 D、看波形治百病）在 PID 入门、PID 进阶和 PID 调参实战那几篇已经讲透了，这里只强调时序关系。

最容易踩的两个时序坑

顺手补一个：传感器进 PID 前先滤波

采集到的编码器、陀螺数据有高频噪声，直接喂给 PID 的 D 项会被 Kd 放大成持续抖动。一个又便宜又好用的办法是一阶低通：

// 一阶低通：新值占 0.3，旧值占 0.7，平滑又便宜
Encoder = Encoder * 0.7f + new_value * 0.3f;

融合姿态角同理。互补滤波是工程上最常用的：

// dt = 0.005s；0.98 越大 => 越信陀螺（高通）
float Complementary_Filter(float acc_ang, float gyro_rate, float dt) {
    static float angle = 0;
    angle = 0.98f * (angle + gyro_rate * dt) + 0.02f * acc_ang;
    return angle;
}

四、状态机：把整车行为拆成”一次只演一个角色”

控制环管的是”这一拍怎么打方向”，但整车在赛道上还有更宏观的行为切换：在起跑线待命、起步加速、跑直道、过弯道、到了十字路口要决策、到终点要精确停靠、丢线了要找回、出意外要急停……这些行为怎么管？答案是有限状态机（FSM）。

这就是状态机最大的价值：降耦合、易调试。把复杂行为拆成独立状态，每个状态只管单一功能。智能车国赛代码多年都用状态机管理直道、弯道、十字、丢线、急停；自动驾驶的行为规划也用分层有限状态机（HFSM），状态名都很像，比如 FORWARD_DRIVE、STOP_SIGN_WAIT、CROSS_INTERSECTION。

整车主状态机骨架

注意急停（ESTOP）能从任何状态进入——这是最高优先级，下面代码里会体现（图里只画了几条代表线，实际是所有状态都能转）：

typedef enum {
    ST_IDLE, ST_START, ST_STRAIGHT, ST_CURVE,
    ST_CROSS, ST_PARK, ST_LOST, ST_ESTOP
} CarState;

CarState st = ST_IDLE;

void State_Machine(void) {
    if (estop_flag) { st = ST_ESTOP; }   // 急停最高优先级，先判
    switch (st) {
        case ST_IDLE:     if (start_btn) st = ST_START;       break;
        case ST_START:    if (moving)    st = ST_STRAIGHT;    break;
        case ST_STRAIGHT: if (is_cross())      st = ST_CROSS;
                          else if (is_curve()) st = ST_CURVE;
                          else if (line_lost)  st = ST_LOST;  break;
        case ST_CURVE:    if (!is_curve())     st = ST_STRAIGHT;
                          else if (line_lost)  st = ST_LOST;  break;
        case ST_CROSS:    Cross_FillLine();
                          if (passed) st = ST_STRAIGHT;       break;
        case ST_LOST:     Recover_ByLastError();
                          if (line_found) st = ST_STRAIGHT;   break;
        case ST_PARK:     Precise_Stop();                     break;
        case ST_ESTOP:    Set_Motor(0, 0);                    break;
    }
}

状态机最容易写错的地方

五、保护逻辑：能拿分的车，先得是”摔不死”的车

开篇那一篇讲过电赛的拿分逻辑——有一堆”失败即 0 分”的红线（冲出赛道、超时等等）。所以整车软件里，保护逻辑不是锦上添花，而是保命。前面控制环代码里那行 if (++vision_timeout > VTO) Set_Motor_Safe(); 就是保护段的入口。这里展开两个最关键的。

视觉超时降级：信号断了别闭眼猛踩

这是新手最容易忽略、又最容易翻车的地方。注意一个事实：摄像头帧率（60~100Hz）远低于控制环（200Hz）。也就是说，控制环跑两三拍，视觉才更新一帧。如果某一拍没有新帧，或者连续丢线超过阈值了，你绝不能拿过期的、无效的图像去盲控。

具体做法：设一个看门狗 / 超时计数器，每来一帧新数据就清零，控制环每拍 +1。超过阈值就降级——保持上一个有效打角、减速或限速直行；严重时直接急停。阈值各队按自己车的特性定。视觉那一篇也讲过同款思路：通信超时（比如超过 100ms 没收到包）就降级到灰度或 IMU 兜底，两处其实是一回事。

丢线找回：记住”最后看见路的方向”

丢线之后怎么回到赛道？核心思路是记忆最后一次有效偏差：

• 设一个 last_error，没丢线时持续更新它；
• 一旦判定丢线，就冻结这个值；
• 用冻结的偏差判断车是往哪边出去的，据此朝相反方向打角，把车拽回赛道。

判丢线常用”全行扫描”：从图像底部往上扫，一直扫到最上面一行还找不到赛道边界，就判为丢线。

六、一条贯穿始终的硬道理：机械定上限，软件定下限

最后，讲一个比任何代码都重要的认知，来自哈工大紫丁香队的血泪经验：

他们有两个特别值得记的故事：

还有一条赛场铁律，宁可多说一遍：

想找完整工程当范本？

光看片段不过瘾，下面几个开源仓库可以拿来研究整车是怎么组织的：

• Sakuramdd/SeekFree_RT1064_Opensource_Library：逐飞 RT1064 视觉组开源库，标准三层 + code(image/control/init)，研究分层与解耦的最佳范本。
• woai66/SeekFree_MSPM0G3507_Opensource_Library：逐飞库移植到 TI MSPM0G3507，直接对应 TI 赛道，是芯片解耦平移的活样本。
• Jerrysupreme/XJTU-VISON_SMARTCAR_2025：西安交大 2025 智能视觉组完整参赛级工程，底盘 RT1064 + 摄像头，学整车怎么组织。
• Blight001/SmartCarCameraTrackingSimulation：Unity 做的赛道仿真，10 款赛道含国赛道，还能逐帧回溯复盘”为什么冲出赛道”——没硬件时调循迹、调参、复盘的神器。
• hxk55668/PID_CAR-STM32-FREERTOS-：想用 FreeRTOS 组织控制/通信/显示任务的，可以参考这个。

更全的开源清单和现场调试速查表，留到下一篇集中给。

小结：把这一篇钉进脑子

到这里，整车软件的骨架就立起来了。回顾一下这几条心法：

• ☐ 分层：App / 中间件 / Driver / HAL 四层，上层只调下层、下层不反调，设备层禁碰芯片 API——换芯片只改驱动层。
• ☐ 调度：电赛首选前后台裸机（主循环跑慢任务 + 定时器中断跑控制环），任务真多了再考虑 RTOS。
• ☐ 控制环：5ms 一拍（200Hz），按”采集→融合→串级 PID→输出→保护”死顺序走，内环快于外环，ISR 只做核心、耗时操作甩主循环。
• ☐ 状态机：把整车行为拆成独立状态，急停最高优先级、等待型状态都要超时退出。
• ☐ 保护：视觉超时降级、丢线记忆找回、出界急停——保命优先。
• ☐ 认知：机械定上限、软件定下限；传感器上场前必标定。

软件框架搭好了，但真正决定你能不能拿奖的，是四天三夜里在赛场上把它跑稳、调好、不翻车。下一篇现场作战手册，我们就聊聊四天三夜怎么安排、调试怎么避坑、以及哪些开源仓库值得你现在就 star。

本文是 「从 0 到 1 带你打电赛 · 小车电控篇」 系列（共 12 篇）第 3 篇。

1. 第1篇 · 拿奖逻辑：把比赛拆成小目标
2. 第2篇 · 赛题进化史与押题
3. 第3篇 · 整车搭建与代码框架（本篇）
4. 第4篇 · 电机驱动与电源地基
5. 第5篇 · 感知：灰度/电磁/编码器/IMU
6. 第6篇 · PID 入门：搞懂 P/I/D
7. 第7篇 · PID 进阶：串级+工程补丁
8. 第8篇 · PID 调参实战(核心)
9. 第9篇 · 进阶控制：几时该上
10. 第10篇 · K230 视觉与通信协议
11. 第11篇 · 状态机与整车软件
12. 第12篇 · 现场作战+避坑+开源

前两篇我们把”这比赛在比什么””出题人爱出什么”聊清楚了。从这一篇开始，我们正式动手——但先别急着掏出电烙铁。一支队伍的上限，往往不是某个调参的瞬间决定的，而是开赛前那个”0 阶段”就埋下的：人怎么分工、主控选谁、代码骨架怎么搭。

这就好比盖楼。地基和承重结构得在挖第一锹土之前想清楚，等楼盖到一半才发现柱子位置不对，那不是修修补补能解决的，是要拆了重来的。而电赛只有四天三夜，没有”重来”的预算。这一篇我们就把这套地基打牢，让你后面写算法、调参数的时候，能做到”现场只改参数，不改架构”。

三个人，怎么分这摊活

小车赛道的队伍通常是三个人。最舒服、也最常见的分工是这样切的：

• 硬件 / 机械：负责选电机、画 PCB 或飞线、电源、机械结构、传感器布板与焊接。这个人手要稳、要懂模拟电路，是整车能不能”通电不冒烟”的第一道关。
• 电控软件：负责主控固件——电机驱动、PID、循迹、状态机、各路通信的整合。这是把所有零件”捏成一辆会跑的车”的人。
• 视觉算法：负责摄像头那一摊——巡线、识别色块/二维码/数字，把图像处理成一个个”结论”发给主控。

这里先埋个伏笔：视觉和主控之间”只传结论不传整张图”的协议怎么设计，是《视觉与通信》一篇的重头戏，这里点到为止。

主控选谁：为什么 2024 年起电赛主推 TI 的 MSPM0

如果你是 2023 年以前打电赛，主控基本就是 STM32。但从 2024 年开始，电赛官方主推的是 TI 的 MSPM0G3507，尤其是智能小车这类题（比如 2024 年 H 题”自动行驶小车”）。很多人第一反应是”我 STM32 还没玩明白，又要换芯片？”——别慌。这俩的关系，我们后面会讲透：STM32 是你练手的”训练场”，MSPM0 是你上场的”主战场”，而且练通的算法能整段搬过去。

先看 MSPM0G3507 这颗芯片本身。它是一颗 Arm Cortex-M0+ 内核、主频 80MHz 的”混合信号”单片机。所谓”混合信号”，意思是它不只擅长跑数字逻辑，模拟外设也特别强——这正好戳中小车的需求。核心规格：

一个必须提前知道的”反直觉硬伤”：硬件编码器接口只有一路

这是 MSPM0 相对 STM32 最大的坑，选型和布线之前必须想清楚，否则到现场才发现就晚了。

STM32 几乎每个定时器都能配成编码器接口模式，你想测两个电机的转速，随便挑两个定时器就行。但 MSPM0G 全芯片只有一个定时器（常说的 TIMG8）硬件支持 QEI 正交编码器解码。也就是说，硬件层面你只能”白嫖”一路编码器。

那双电机怎么办？两条路：

• 路线 A（硬件 QEI）：用那唯一一路 TIMG8，硬件自动计数 + 判方向，几乎不占 CPU。这是首选。
• 路线 B（GPIO 外部中断）：A/B 两相各接一个 GPIO，上升沿触发中断，在中断里读另一相的电平判方向，再用一个 20ms 周期的定时器去数脉冲算速度。代价是高转速时容易漏脉冲、把中断占满。

所以双电机的典型方案是：一路走硬件 QEI，另一路退回 GPIO 中断（给它最高优先级），或者上一颗外部计数芯片。

编码器测速本身的原理很直白，就像数脉冲过了几个：车每跑一段，电机转一点，编码器吐出一串脉冲；你每隔固定时间（比如 20ms）数一次这段时间内新增了多少脉冲，数得越多说明跑得越快。A、B 相脉冲的先后顺序，还能告诉你是前进还是后退。具体的编码器接法和 IMU 融合，我们留到《感知：灰度/电磁/编码器/IMU》一篇细讲。

开发环境：SysConfig、IDE 和两种下载方式

SysConfig：TI 版的”装修图纸软件”

TI 给 MSPM0 配了一个图形化配置工具叫 SysConfig，作用相当于 STM32 玩家熟悉的 CubeMX。

它就像装修前用图纸软件拖拽布局：你在图上点哪个插座（引脚）接什么电器（外设），软件自动帮你把”水电图”（一个叫 ti_msp_dl_config.h 的头文件，里面有 SYSCFG_DL_init() 初始化函数）画好，你不用自己一根根去配寄存器。配 PWM 在 TIMER-PWM 分类下、配编码器在 TIMER-QEI、配 ADC 在 ADC12、配运放在 OPA。配完它会生成一堆实例宏，比如 PWM_0_INST、QEI_0_INST、UART_0_INST，你代码里直接用这些名字就行。

配 PWM 的时候，有个关系要记牢：

$$\text{频率}=\frac{\text{时钟}}{\text{分频}\cdot(\text{period}+1)}$$

向上计数时，占空比 $=\frac{\text{CCR}}{\text{period}+1}$。立创开发板的电机驱动例程用 80MHz 时钟、period 设 10000，实测出来约 8kHz。运行时动态改占空比就一行：

// 设置占空比 (向上计数: duty = CCR/(period+1))
DL_TimerG_setCaptureCompareValue(PWM_0_INST, 1000, DL_TIMER_CC_1_INDEX);
// 如果 SysConfig 里没勾 "Start Timer"，需要手动启动一次
DL_TimerG_startCounter(PWM_0_INST);
// 读编码器 QEI 计数
uint32_t cnt = DL_Timer_getTimerCount(QEI_0_INST);

注意 MSPM0 的 API 全是 DL_ 前缀（DriverLib 的意思），这和 STM32 的 HAL_/LL_ 不一样。再记两个小口诀：PWM 占空比建议别超过 95%；改 PWM 频率（改 period）会同时改变占空比的分辨率（period 越小，占空比能分的档越粗），要兼顾。PWM 频率电赛常用 8kHz 到 32kHz 这个区间，低于 20kHz 左右电机会有可闻的”啸叫”，想安静点就往高了选。

IDE：CCS / Keil / IAR 怎么挑

• CCS：TI 官方的，免费，基于 Eclipse，内置 SysConfig，配套最全。新手最省心。
• Keil MDK：电赛圈最主流，因为大家生态熟、学校积累多。但要注意版本——需要 uVision v5.38a 以上 + AC6 编译器 v6.16 以上，版本太旧装不上 MSPM0 的支持包。
• IAR：也支持，用的人相对少。
• VSCode：它本身不是官方 IDE，但社区常用 VSCode + Keil（靠插件）或 VSCode + CMake + GCC 来获得更现代的编辑体验，编译下载还是靠 Keil 或命令行。

一句话：图省心、从零起步用 CCS；要沿用学校积累、跟队友保持一致就用 Keil。

下载：SWD 仿真器 vs BSL 串口

这俩的区别，可以类比成上网方式：

• SWD（专线宽带）：用板载的 XDS110 或外接 DAP-Link / J-Link，四根线（SWCLK / SWDIO / GND / 3V3）。不仅能下载，还能实时看程序在干嘛、打断点单步调试。开发期首选。
• BSL 串口（手机热点应急）：用 TI 的 UniFlash 工具，通过 USB 转串口把程序灌进去，没仿真器也能用，但只能灌不能调。

BSL 这条路有两个非常容易翻车的细节：

结论很简单：开发期老老实实用板载 XDS110 或 DAP-Link 走 SWD，能调试又省事；BSL 留作”手头没仿真器”时的应急手段。

重头戏：让”算法和芯片解耦”的分层框架

到这里，才是这一篇真正的核心。前面铺垫了这么多，就是为了引出一个问题：STM32 练手、MSPM0 上场，凭什么练通的算法能整段搬过去？

答案不在芯片，在代码架构。

为什么要分层

设想一下，如果你的 PID 函数里直接写满了 HAL_GPIO_WritePin(...) 这种 STM32 专属的芯片 API，那换到 MSPM0 的时候，整个 PID 函数都得跟着改——因为它和具体芯片”焊死”在一起了。这就是没分层的下场：换芯片 = 满地找改 = 平移变重写。

分层架构的思路，像点外卖：

• 你（App 应用层）：只对着 App 下单，决定”我要吃啥、车要怎么跑”，从不进后厨。这里放状态机和决策。
• App 平台（中间件层）：把订单翻译给骑手和商家，承载 PID、滤波、通信协议、元素识别这些和芯片无关的算法。
• 骑手 / 灶台（驱动层 + HAL）：干脏活累活，真正去配寄存器、读写引脚。

换城市（换芯片）时，你点外卖的方式（算法）一字不改，变的只是当地的骑手和店家（驱动层）。这就是”算法和芯片解耦”的本质。

这套范式不是我们瞎编的，它直接借鉴了智能车圈久经考验的逐飞（SeekFree）开源库的分层结构：

一条不能破的铁律

分层能不能起作用，全看一条铁律守不守得住：

逐飞库就是这么干的：设备层（管摄像头/陀螺/屏的初始化）只允许调驱动层的接口，不准碰最底层的芯片 API。这样换 MCU 只改驱动层，中间件和 App 原样平移。

这套库有多能打？同一份逐飞库已经移植到了 RT1064、英飞凌 TC264、STC32，以及 TI 的 MSPM0G3507（对应 2025 TI 板电赛）——上层算法共用，差异全集中在底层驱动。这就是分层解耦价值的活证据。

一个可照抄的目录骨架

落到实处，你的工程目录可以这么切：

project/
├── App/                 # 应用层：你写的核心逻辑
│   ├── fsm.c/h          #   状态机：待命/起步/直道/弯道/路口/停靠/找回/急停
│   └── control_task.c   #   控制环调度：采集→融合→串级PID→输出→保护
├── Middleware/          # 中间件层：芯片无关的算法
│   ├── pid.c/h          #   PID（位置式/增量式）
│   ├── filter.c/h       #   滤波（一阶低通/互补）
│   └── protocol.c/h     #   通信帧解析
├── Driver/              # 驱动层：换芯片主要改这里
│   ├── motor.c/h        #   电机：把"带符号速度"翻译成PWM+方向
│   ├── encoder.c/h      #   编码器读速
│   ├── gray.c/h         #   灰度采集
│   └── uart.c/h         #   串口收发
└── HAL/                 # 芯片相关：DriverLib / 寄存器
    └── (SysConfig 生成的 ti_msp_dl_config.h 等)

关键在于接口的方向：App 调中间件和驱动，中间件和驱动里绝不出现任何芯片专属 API。比如电机驱动这一层，对上只暴露一个”给我一个带符号的速度”的接口，符号决定正反转、绝对值决定 PWM 大小，至于底下怎么配 PWM 寄存器，全藏在驱动层里：

// 中间件层：PID 算出一个带符号输出，完全不知道芯片是谁
int pwm = (int)pid_calc(&speed_pid, target_speed, get_encoder_count());

// 驱动层：把带符号输出翻译成具体的正反转 + PWM（这层才碰芯片）
void motor_set(int pwm) {
    if (pwm > 0)       set_motor(0, pwm);   // 正转
    else if (pwm < 0)  set_motor(-pwm, 0);  // 反转（取绝对值）
    else               stop_motor();
}

pid_calc 这个函数里只有数学，没有一行芯片代码，所以它在 STM32 上调通了，搬到 MSPM0 上一个字都不用改。这就是”练通的算法整段平移”的底气。

STM32 MSPM0 平移心法

很多人迁移时的第一反应是”把每一个 HAL_xxx 逐行翻译成 DL_xxx“。这是最痛苦、最容易错的做法，千万别这么干。

TI 官方在《从 STM32 到 MSPM0 迁移指南》（文档号 ZHCABX9B，能搜到）里给出的标准心法是：先把你的应用逻辑理解透，然后拿一份最接近的 MSPM0 官方例程当骨架，把你的 PID、循迹这些算法层原样搬进去，只重写外设的初始化和读写。

官方给的工具链对照表，迁移时贴在显示器边上很有用：

有几个外设层面的差异，是平移时最容易”反咬”算法层假设的地方，列成清单逐条核对：

• ☐ GPIO 拆成了两块：STM32 一个 GPIO 概念，MSPM0 拆成 GPIO（读写 / 中断）+ IOMUX（引脚复用），配引脚和读写是分开的。
• ☐ 硬件编码器接口只有一路 QEI（前面强调过的硬伤），双电机方案要提前定好。
• ☐ UART 的 FIFO 只有 4 字节（STM32 是 8 字节），高速收发更容易溢出，而且不支持自动波特率检测。
• ☐ UART 中断里不要照搬习惯去调 NVIC_ClearPendingIRQ()——官方教程明确提醒过，照搬 STM32 写法会出问题。
• ☐ 时钟树、NVIC、中断模型和 STM32 不一样，从官方 example 起步能帮你绕开大部分坑。

官方迁移指南把整个流程总结成五步，照着走就行：① 对照产品系列表选定 MSPM0 器件 → ② 订 LaunchPad 开发板（LP-MSPM0G3507）→ ③ 装 IDE + SDK → ④ 软件移植（从最接近的官方例程改起，不是逐行替换 API）→ ⑤ 调试验证。

有哪些现成的模板和库可以站在肩膀上

完全从零搭框架很费时间。下面这几个仓库都是经过电赛验证的，按你的处境挑一个当起点：

• TI 官方 mspm0-sdk：DriverLib + 海量外设例程（GPIO / Timer / PWM / ADC / UART / DMA / OPA 全都有）。这是所有上层方案的底座，也是”从最接近的 example 改起”那个 example 的来源。一手权威，必装。
• ZLC_MSPM0_Peripheral_Library：2024 电赛 H 题一等奖（山大威海）的外设库，编码器、电机（DRV8701E 双路）、舵机 PWM、8 路灰度、IMU、无线串口一应俱全，还附了设计报告和环境配置文档。想看一等奖的完整车软件栈长什么样，看这个。
• PIDCarTemplate-MSPM0G3507：两轮 / 四轮 PID 小车模板，封装好了 Delay / Encoder / Motor / 按键（短按长按双击）/ MPU6050 / OLED / 蓝牙 / 灰度，clone 下来调 API 就能开发。从零起步直接套模板的首选。
• woai66 的逐飞 MSPM0 移植库：把上面讲的逐飞分层库移植到了 MSPM0，对应 2025 TI 板电赛。想要”芯片解耦平移”那套完整范本，看它。
• danshoujieyi/TI-MSPM0G3507：电赛指定板模板，裸机版 + FreeRTOS 版 + RT-Thread 版都有（Keil5 + VSCode）。想上 RTOS 或要 VSCode 工作流的直接用。
• MSPM0-CMAKE-GCC-Template：GCC + CMake 模板，想脱离 Keil、用 VSCode + 命令行现代工作流的首选。

更全的开源仓库点评（含视觉车、平衡车、仿真工具），我们放在收官的《现场作战手册》一篇里集中评注，这里先给够你起步用的几个。

一些选型和架构上的经验之谈

最后几条是过来人趟出来的，写代码之前先记在心里。

调度、控制环时序、状态机怎么把所有模块串成一辆会跑的车，是《状态机与整车软件》那一篇的主题，到时候我们会给出完整的主控制环伪代码和状态图。

把这一篇的地基打牢，你就有了一套”算法写一次、芯片换着用”的框架。但框架终究是个空壳，真正让车动起来的第一步，是让电机听话——电机驱动、PWM 和电源这套电控地基，我们下一篇见。