1. 为什么值得花时间吃透 ST MC SDK 的工程结构
很多人第一次接触 ST 的电机控制生态，路径都差不多：装好 Motor Control WorkBench，点几下鼠标生成工程，编译下载，电机转起来了，然后就没有然后了。等到需要改一个采样电阻阻值、换一套霍尔安装角度、或者把控制频率从 16kHz 调到 20kHz 的时候，面对满屏的MC_前缀文件和层层嵌套的#include，瞬间就懵了。我见过太多人卡在这一步，最后选择推倒重来，自己从零手写 FOC，结果又在电流采样时序和转子初始位置检测上反复翻车。
这篇内容就是写给这批人的。ST MC SDK（Motor Control SDK）配合WorkBench这套工具链，本质上是 ST 把一套经过量产验证的FOC（磁场定向控制）固件框架，用图形化配置的方式暴露给你。它解决的核心问题是：让不懂电机控制算法细节的嵌入式工程师，也能在STM32上快速跑通一套可用的电机控制方案。但"快速跑通"和"真正掌握"之间隔着一整个工程结构的理解。
适合谁来读：有 STM32 基础、会用 CubeMX、但被 MC SDK 生成的工程结构劝退过的嵌入式工程师；正在做PMSM 无感 FOC 控制或者霍尔编码器电机 PID 控制项目，需要深度定制固件的人；以及拿基于 STM32 的毕业设计做电机方向、需要讲清楚工程架构的学生。我会从工程目录的每一层讲起，把 WorkBench 生成的代码到底做了什么、为什么这么分层、哪些文件能改哪些不能碰，全部拆开讲透。读完你至少能做到：拿到任何一个 MC SDK 工程，半小时内定位到你想改的那一行。
2. 先搞清楚 WorkBench 到底帮你生成了什么
2.1 从配置界面到代码：一次生成动作背后的三件事
WorkBench 的界面看起来像个普通的配置工具，左边选电机参数，右边选功率板，中间勾选各种功能。但点下"Generate"之后，它实际做了三件独立的事，理解这三件事是理解整个工程结构的前提。
第一件是参数固化。你在界面上填的电机极对数、额定电流、采样电阻阻值、母线电压分压比、PID 初始增益，全部被写进一个头文件里，通常是pmsm_motor_parameters.h、drive_parameters.h、power_stage_parameters.h这几个。这些是编译期常量，不是运行期变量，改完必须重新编译。
第二件是框架代码生成。WorkBench 会根据你选的拓扑（单电阻、三电阻、ICS 电流采样）和控制模式（有霍尔、无感、编码器），生成对应的状态机、中断服务函数骨架、以及各功能模块的初始化调用链。这部分代码在MC_Library或者MCSDK_vX.X.X目录下，是 ST 的固件库。
第三件是应用层胶水代码。也就是main.c、mc_app.c、mc_interface.c这些，负责把 STM32 的 HAL 库、MC 固件库、以及你的用户代码粘在一起。这部分是你日常改得最多的。
注意：WorkBench 每次重新生成工程，都会覆盖它自己生成的那部分文件。如果你把用户代码写进了它管理的文件里，重新生成就全没了。这是新手最容易踩的坑，后面会专门讲怎么规避。
2.2 工程目录的典型分层结构
一个标准的 MC SDK 工程，目录结构大致是这样的（不同版本略有差异，但逻辑一致）：
Project/ ├── MCU_Config/ // CubeMX 生成的底层配置 │ ├── Inc/ │ └── Src/ ├── MCSDK_v6.x.x/ // ST 电机控制固件库 │ ├── MCLib/ │ │ ├── Inc/ │ │ └── Src/ │ └── ... ├── Application/ // 应用层 │ ├── User/ │ └── ... ├── Middlewares/ ├── Drivers/ └── ...这个分层不是随便分的。MCU_Config管的是芯片外设，定时器怎么配、ADC 怎么触发、GPIO 怎么映射，这些和电机算法无关，是纯硬件抽象。MCSDK管的是算法，坐标变换、PID、状态机、观测器，这些和具体芯片无关，是纯控制逻辑。Application管的是业务，按键怎么响应、串口怎么通信、故障怎么处理，这些和算法无关，是纯应用逻辑。
三层各管各的，好处是换芯片只动第一层，换算法只动第二层，换产品功能只动第三层。坏处是新手看代码时跳来跳去，一个电机启动流程要横跨三个目录才能看全。我的建议是：先顺着调用链走一遍，再按目录理解职责。调用链是纵向的，目录是横向的，先纵后横，脑子里才有立体结构。
2.3 关键文件速查：哪些能改，哪些别碰
我把工程里最常打交道的文件列个表，标注清楚可改性，这个表建议你收藏：
| 文件/目录 | 作用 | 可改性 | 说明 |
|---|---|---|---|
pmsm_motor_parameters.h | 电机本体参数 | 可改 | WorkBench 生成，改完重新编译 |
drive_parameters.h | 控制参数、PID 增益 | 可改 | 同上，但部分参数运行期可调 |
power_stage_parameters.h | 功率板参数 | 可改 | 采样电阻、分压比等 |
mc_configuration_registers.h | 配置寄存器映射 | 慎改 | 与 WorkBench 配置强绑定 |
mc_interface.c | 用户接口层 | 可改 | 加自己的按键、串口逻辑 |
mc_app.c | 应用状态机 | 可改 | 启动、停止、故障处理 |
mc_tasks.c | 任务调度 | 慎改 | 中断优先级相关，改错会崩 |
MCLib/Src/*.c | 算法实现 | 别碰 | ST 固件库，改了没意义 |
stm32g4xx_mc_it.c | 中断服务 | 慎改 | 电机控制中断入口 |
这张表的核心信息是：算法层别碰，配置层随便改，应用层是你的地盘。很多人一上来就想改MCLib里的 PID 实现，觉得 ST 写得不够好，这是典型的用力用错地方。ST 的算法经过大量量产验证，你要改的应该是喂给它的参数，而不是算法本身。
3. FOC 控制链路在工程里的完整映射
3.1 从电流采样到 PWM 输出：一次控制周期发生了什么
要理解工程结构，必须先理解 FOC 一个控制周期内的数据流。假设你用的是三电阻采样、有霍尔传感器、控制频率 16kHz，那么每 62.5 微秒发生一次完整链路：
- ADC 触发：定时器在 PWM 中心对齐的特定时刻触发 ADC，采样三相电流和母线电压。
- 电流重构：从采样值还原出 Ia、Ib、Ic，三电阻方案直接读三个通道，单电阻方案要靠 PWM 占空比推算。
- Clarke 变换：Ia、Ib、Ic 变成 Iα、Iβ，从三相静止坐标系到两相静止坐标系。
- Park 变换：Iα、Iβ 结合转子电角度 θ，变成 Id、Iq，从静止坐标系到旋转坐标系。
- PID 调节：Id、Iq 与目标值比较，经过 PID 算出 Vd、Vq。
- 反 Park 变换：Vd、Vq 结合 θ 变回 Vα、Vβ。
- SVPWM 生成：Vα、Vβ 算出三相占空比，写入定时器比较寄存器。
- 位置更新：霍尔或观测器更新转子角度，准备下一个周期。
这八步在工程里对应哪些文件？ADC 触发在MCU_Config的定时器配置里，电流重构和坐标变换在MCLib的mc_transform.c和mc_currents.c，PID 在mc_pid_regulators.c，SVPWM 在mc_pwm_curr_fdbk.c，位置更新在mc_hall.c或mc_observer.c。你看，一个控制周期横跨了几乎所有模块，这就是为什么单看某个文件永远看不懂。
3.2 中断优先级：为什么电机控制中断不能被打断
FOC 对时序极其敏感。电流采样必须在 PWM 特定时刻，坐标变换必须在采样之后立刻做，PWM 更新必须在下一个周期开始前完成。任何一个环节被延迟，轻则电流波形畸变，重则电机失步。
所以工程里电机控制中断的优先级是最高的，通常是ADC1_2_IRQn或者专门的TIM1_UP_TIM16_IRQn，抢占优先级设为 0。你在mc_tasks.c或者stm32g4xx_mc_it.c里能看到类似这样的配置：
HAL_NVIC_SetPriority(ADC1_2_IRQn, 0, 0); HAL_NVIC_EnableIRQ(ADC1_2_IRQn);提示：如果你要加串口通信、按键扫描这些任务，优先级一定要低于电机控制中断。我见过有人在 ADC 中断里加
printf，结果电机一转就卡死，因为串口发送阻塞了控制周期。
3.3 状态机：电机是怎么从静止到转起来的
MC SDK 的核心是一个状态机，定义在mc_state_machine.c里。状态包括IDLE、START、RUN、STOP、FAULT等。启动流程大致是：
IDLE：等待启动命令。START：执行对齐（有霍尔的话可能跳过）、开环强拖（无感方案）、转子初始位置检测。RUN：闭环运行，PID 接管。STOP：按配置执行刹车或自由停车。FAULT：过流、过压、欠压、堵转等触发，进入保护。
这个状态机的转移条件，一部分来自你的应用层命令（MC_StartMotor()、MC_StopMotor()），一部分来自硬件故障信号。理解状态机的关键是搞清楚每个状态的进入条件和退出条件，这决定了你的电机为什么起不来、为什么转一下就停。
4. 从零搭建一个 FOC 工程的完整实操
4.1 环境准备与工具版本选择
先说工具链。你需要的东西：
- STM32CubeMX：配底层外设，版本建议 6.10 以上。
- Motor Control WorkBench：配电机参数和算法，版本要和 MC SDK 匹配。
- MC SDK 固件包：从 ST 官网下载，解压到本地。
- IDE：Keil MDK、IAR、STM32CubeIDE 都行，我用 CubeIDE，免费且和 CubeMX 集成好。
版本匹配这件事必须强调。WorkBench 6.2 配 MC SDK 6.2，WorkBench 6.3 配 MC SDK 6.3，混用会出现生成的代码引用不存在的宏。我踩过一次坑，用 6.3 的 WorkBench 配 6.2 的库，编译报了几十个undefined reference，查了半天才发现是版本问题。
4.2 WorkBench 配置的关键参数怎么填
打开 WorkBench，新建工程，选你的芯片型号（比如 STM32G431RB，这是 ST 官方电机控制板常用的）。然后按顺序填：
电机参数：极对数、额定电流、额定电压、相电阻、相电感、反电动势常数。这些从电机手册拿，没有手册就实测。极对数可以用手转一圈数霍尔跳变次数除以 6 得到。相电阻用电桥或者万用表测线电阻除以 2。相电感用电感表测，没有的话用 LCR 表。
功率板参数：采样电阻阻值、运放增益、母线分压比、死区时间。采样电阻和运放增益决定了电流采样范围，公式是：
最大可测电流 = (ADC参考电压 / 运放增益) / 采样电阻比如参考电压 3.3V，运放增益 10，采样电阻 0.01Ω，那么最大可测电流 = (3.3/10)/0.01 = 33A。这个值要大于电机峰值电流，否则大电流时采样饱和，FOC 直接失控。
控制参数：控制频率、PWM 频率、电流环带宽、速度环带宽。控制频率一般等于 PWM 频率，16kHz 或 20kHz 常见。电流环带宽取控制频率的 1/10 到 1/20，速度环再低一个数量级。
4.3 生成工程后的第一次编译与下载
配置完点生成，WorkBench 会调用 CubeMX 生成底层代码，再叠加 MC 固件库。生成完用 IDE 打开，先别急着改代码，直接编译。如果编译报错，八成是库路径没配对，检查 IDE 的 include 路径里有没有 MC SDK 的MCLib/Inc。
编译通过后下载。第一次上电，电机不要接负载，手边准备急停开关。用 WorkBench 自带的 Monitor 工具或者串口助手发启动命令，观察电机是否平稳转动。如果抖动、异响、或者直接过流保护，先别怀疑算法，检查这三项：霍尔相序对不对、电流采样极性对不对、电机参数填得准不准。
4.4 用户代码该写在哪里
这是最关键的实操点。WorkBench 管理的文件重新生成会被覆盖，所以你的代码必须写在它不管的地方。我的做法是：
- 在
Application/User/下新建my_app.c和my_app.h，所有业务逻辑写这里。 - 在
mc_interface.c里只加一行调用MyApp_Init()，这个文件 WorkBench 会保留用户添加的代码段（有/* USER CODE BEGIN */标记）。 - 中断里要加逻辑，写在
stm32g4xx_mc_it.c的USER CODE段里。
注意：
USER CODE BEGIN和USER CODE END之间的内容，WorkBench 重新生成时会保留。这是 ST 留的官方后门，一定要用好。我见过有人把代码写在标记外面，重新生成后哭都来不及。
5. 常见问题与排查技巧实录
5.1 电机不转或转一下就停的排查顺序
这个问题太常见了，我整理了一个排查顺序，按这个走基本能定位：
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 完全不转，无电流 | 启动命令没发出去 | 检查MC_StartMotor()是否被调用 |
| 转一下停，报过流 | 电流采样极性反了 | 示波器看采样波形，或交换两相 |
| 抖动不转 | 霍尔相序错 | 手动转电机，看霍尔状态变化顺序 |
| 转但异响 | 电机参数不准 | 重新测相电阻、相电感 |
| 低速可以高速失步 | 观测器参数不对 | 调无感观测器增益 |
| 一上电就保护 | 母线电压检测错 | 检查分压比配置 |
5.2 电流采样相关的坑
电流采样是 FOC 里最容易出问题的地方。三电阻采样要注意采样时刻必须在 PWM 下桥臂导通期间，否则采到的是续流电流。单电阻采样更麻烦，要靠占空比推算，低占空比时采样窗口太窄，需要特殊处理。
我遇到过一个典型案例：电机低速时电流波形正常，高速时电流畸变严重。查了半天发现是采样时刻配置在 PWM 中心，但高速时占空比接近 100%，中心点已经不在下桥臂导通区了。解决办法是把采样时刻改到 PWM 周期的特定偏移位置，WorkBench 里有这个配置项，叫 "Sampling Point"。
5.3 无感 FOC 的转子初始位置检测
FOC 转子初始位置检测是无感方案启动的第一步。电机静止时观测器没有反电动势可用，必须通过注入高频信号或者施加短时脉冲，根据电流响应判断转子位置。MC SDK 里这部分在mc_observer.c和启动状态机里。
常见问题是检测不准，导致启动时反转或者抖动。影响因素：注入信号幅值、检测时间、电机凸极率。表贴式电机凸极率低，检测难度大，可能需要改用高频注入法。内置式电机凸极率高，脉冲注入就够。
提示：如果初始位置检测总是不准，先确认电机是不是表贴式的。表贴式电机用脉冲注入法效果差，这是物理特性决定的，不是代码问题。
5.4 重新生成工程后代码丢失的预防
前面提过，WorkBench 重新生成会覆盖它管理的文件。预防措施：
- 所有用户代码写在
USER CODE BEGIN/END之间。 - 独立的功能模块放在
Application/User/下，不放在 WorkBench 管理的目录。 - 用 Git 管理工程，每次重新生成前先提交，生成后 diff 一下看丢了什么。
- 如果非要改 WorkBench 管理的文件，改完立刻备份，或者写个脚本在生成后自动打补丁。
我用的是第 3 种，Git 加 diff，最稳妥。每次 WorkBench 重新生成后，git diff一眼就能看出哪些用户代码被覆盖了，直接恢复。
6. 工程结构的深度定制与扩展
6.1 换芯片时工程怎么迁移
从 STM32F103 换到 STM32G431，或者从 G431 换到 G474，工程迁移的核心是底层配置。步骤：
- 在 WorkBench 里改芯片型号，重新生成。
- 检查
MCU_Config下的定时器、ADC、GPIO 配置是否还正确，不同芯片的外设资源不一样。 - 检查中断向量表，
stm32xxxx_mc_it.c文件名会变。 - 重新编译，解决所有
undefined错误。
算法层和应用层基本不用动，这就是分层设计的好处。我做过一次 F103 到 G431 的迁移，算法层一行没改，只调了底层配置，半天搞定。
6.2 加自己的通信协议
产品化项目通常需要上位机通信，比如用串口或者 CAN 上报电流、速度、故障码。做法是在mc_interface.c里加一个通信任务，或者在USER CODE段里加。注意通信任务不能阻塞电机控制中断，用 DMA 或者环形缓冲区。
我一般会定义一个简单的协议帧：帧头 + 命令字 + 数据长度 + 数据 + 校验。上报数据用定时器触发，比如每 10ms 发一帧，不影响控制周期。
6.3 多电机控制的工程组织
有些项目要控两个电机，比如双轮平衡车。MC SDK 默认是单电机，多电机需要实例化两套控制对象。ST 的固件库部分支持多实例，但 WorkBench 不直接生成双电机工程。做法是手动复制一套配置，改掉外设映射，在应用层分别调用。
这个比较进阶，坑也多，主要是中断资源和 ADC 资源的冲突。两个电机不能共用同一个 ADC 中断，要么用两个 ADC，要么用同一个 ADC 但分时采样。我建议新手先跑通单电机，多电机等有经验了再碰。
7. 一些实测下来的经验体会
WorkBench 生成的工程，第一眼看很乱，但乱中有序。我的经验是：不要试图一次看懂所有文件，先顺着一个控制周期走一遍，再顺着启动流程走一遍，两遍下来结构就清楚了。
参数配置这块，电机参数宁可用实测值，不要用手册标称值。手册上的相电阻是 25°C 下的，实际运行时温度升高电阻会变，但至少比瞎填强。相电感尤其重要，填错了电流环直接震荡。
还有一点，ST 的 MC SDK 版本更新挺快，但新版本不一定适合你。我有个项目用 6.2 跑得很稳，升级到 6.3 后无感启动成功率下降，查了半天是观测器默认参数变了。所以升级前一定要在测试台上验证，别直接上产品。
最后说个调试技巧：WorkBench 自带的 Monitor 工具能实时看电流、速度、角度波形，比串口打印方便得多。但它是通过特定通信接口连的，需要你的板子支持。如果没有，就自己用 DAC 输出关键变量到示波器，这是最原始的调试手段，但永远有效。我在USER CODE段里加过一段代码，把 Iq 和速度通过 DAC 输出，示波器上一眼就能看出 PID 调得好不好，比看数字直观多了。
