简介：面向嵌入式电机控制初学者与希望熟悉STM32G4平台的工程师，这份PDF资料以ST电机控制生态为线索，梳理从MC SDK生成FOC代码到CubeMx移植电机工程的入门路径，帮助读者建立工具链、Demo板与自建控制板之间的配置关联。压缩包内仅含1个PDF文件，大小约3.64MB，篇幅轻量，适合按章节查阅和随课翻阅，内容以要点式幻灯片组织，便于快速定位关键配置。已有约900人学习下载，在同类入门资料中具备一定参考度。读者可从中了解Workbench中电机与功率板参数设置、数字与模拟端口配置，以及Timer、编码器、Hall信号、电流电压温度采样等基础环节，并掌握芯片型号未包含在Workbench时借助Customer Board工程的变通思路，为后续FOC调试与代码移植打下基础。整体更偏向概念梳理与工程搭建引导，适合作为动手实践前的路线图。
1. 从一块 Nucleo 板说起：STM32 电机控制这套工具链到底能省掉多少底层活
做 STM32 电机控制的人大多经历过同一个阶段：手里有芯片手册、有驱动电路，就是搞不定 FOC 那套坐标变换和电流环。G4 这颗芯片本来就是冲着数字电源和电机驱动去的，片上的高速 ADC、运放、比较器、高分辨率定时器全摆在那里，可要把它们串成一套能闭环转起来的 FOC，裸写寄存器没几个星期下不来。这套基础篇资源干的是一件很直接的事：把厂商生态里的 Motor Control Workbench、X-CUBE-MCSDK 和 CubeMX 串成一条链路，从选板子、配功率级、生成 FOC 代码，一直走到用 API 接管电机。它适合手上有 G4 板子、想先把电机稳稳转起来再谈优化的工程师，也适合课程设计需要一套最小可跑闭环的人。
2. 装环境与选芯片：MCSDK、CubeMX、ST-LINK 三件套的版本门槛
2.1 软件清单和版本组合
这套工具有个特点：不是装一个软件就完事，而是一条链，任何一环版本对不上，后面生成工程就会莫名其妙地失败。先把清单摆清楚，再谈怎么装。
| 工具 | 在链路里的角色 | 版本要求 | 装错后的典型表现 |
|---|---|---|---|
| STM32CubeMX | 引脚、时钟、HAL 工程生成 | v5.6 以上 | 器件库里找不到 G4，工程生成按钮灰掉 |
| X-CUBE-MCSDK 或 X-CUBE-MCSDK-FUL | Workbench 图形配置 + 电机控制库 | 5.x | 生成的工程和固件包对不上，编译报缺文件 |
| ST-LINK/V2 或 ST-LINK/V3 | 下载与调试 | V2 需固件较新 | 连接目标失败，或虚拟串口不出现 |
| IAR EWARM / Keil MDK / Atollic TrueSTUDIO | 编译与在线调试 | IAR v8.x、MDK v5.x、Atollic 9.0.0 | 器件支持包缺失，链接报错 |
这里有两个选择要提前想清楚。第一个是 MCSDK 装普通版还是 FUL 版。普通版给的是编译好的库和头文件，工程干净、编译快；FUL 版带电机库源码，想改观测器、想打断点看电流环内部变量，就得用 FUL。我一般先装普通版把电机转起来，确认硬件没问题，再换 FUL 去啃底层。第二个是 IDE。Workbench 生成的工程对三家 IDE 都出，但实际用下来，Keil 和 IAR 的工程文件最稳，Atollic 现在用得少了，除非你团队历史工程就在上面，否则别为了尝鲜去折腾。
安装顺序也有讲究：先 CubeMX，再 MCSDK，最后装 IDE 的器件包。因为 MCSDK 安装时会去探测本机 CubeMX 的位置，顺序反了它可能找不到，后面生成工程时提示 CubeMX 路径无效。装完可以用下面这段脚本把关键路径和版本扫一遍，省得进图形界面一个个翻。
import os, glob, sys # 常见安装位置，按自己机器改 candidates = [ r"C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeMX", r"C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeMX\db\mculist", os.path.expandvars(r"%LOCALAPPDATA%\Programs\STM32CubeMX"), ] for p in candidates: if not os.path.exists(p): print(f"[缺失] {p}") continue # 路径里只要出现非 ASCII 字符，后面生成工程大概率翻车 bad = [ch for ch in p if ord(ch) > 127] flag = "含非ASCII字符: " + "".join(bad) if bad else "路径OK" print(f"[存在] {p} -> {flag}") # 找 MCSDK 的 Workbench 可执行文件 for exe in glob.glob(r"C:\Program Files\STMicroelectronics\*MCSDK*\*Workbench*.exe"): print("[MCSDK]", exe)这段脚本干两件事：确认 CubeMX 装没装、装在哪，以及路径里有没有中文或全角字符；顺带把 Workbench 的可执行文件找出来。ord(ch) > 127这个判断就是抓非 ASCII，中文用户名、中文目录名、全角空格都会被它揪出来。输出里出现「含非ASCII字符」就别急着往下走，先重装到纯英文路径，这是后面所有步骤的前提。
2.2 中文路径和 ST-LINK 驱动这两个隐形雷
资料里那句「CubeMX 请不要安装在中文路径下」不是客套话，是血泪经验。CubeMX 生成工程时会写一堆相对路径和 include 路径，中间只要有一层目录名带中文，编译阶段就会出现「找不到 xxx.h」，而且报错信息指向的路径看起来完全正常，让人一头雾水。更隐蔽的是 Windows 用户目录：很多人把工程放在「桌面」或者用户名是中文的C:\Users\张三\下面，CubeMX 默认的工程目录正好落在这儿，于是明明装在了 D 盘英文目录，生成出来还是坏的。解决办法很简单，工程统一放D:\mcsdk_ws\这类纯英文短路径，用户名是中文的就在 D 盘根目录建工作区。
ST-LINK 这边的问题多半出在驱动和克隆件上。正品 V2、V3 插上后设备管理器里应该能看到STLink Virtual COM Port和STLink Debug两个设备，只出现一个或者带黄色感叹号，基本就是驱动没装对。克隆的 V2 还有个坑：CubeProgrammer 会提示固件版本过旧并建议升级，升级过程中一旦断线，调试器就变砖。我的习惯是能连上、能下载就不动固件，除非遇到明确的功能缺失。
装完之后做一次最小验证：新建一个空 CubeMX 工程，选 G474RET6，只配时钟和 SWD 调试口，生成、编译、下载。这一步能过，说明工具链本身没问题，后面电机工程出问题就只需要往配置上找，不用怀疑环境。这个「先跑空工程」的习惯帮我省过很多次误判。
3. 用 Motor Control Workbench 生成 FOC 工程：从 Demo 板到自建板
3.1 Demo 套件快速验证：P-NUCLEO-IHM03 全流程
Workbench 的价值在于把 FOC 里那些琐碎的配置项做成了向导：你告诉它用什么板、什么功率级、什么电机，它把三相互补 PWM、死区、电流采样触发、状态机、速度环参数全给你配好，直接出一份能编译的工程。第一次用，强烈建议拿现成套件走一遍，把链路跑通再换自己的板子。
以 P-NUCLEO-IHM03 为例，流程是这样的：
- 打开 Motor Control Workbench，新建工程，板子类型选对应的 Nucleo 套件。
- 电机选择里挑套件配套的那颗低压云台电机，极对数、额定电流、母线电压按铭牌或资料填。
- 进入配置页，先看电流采样方式。套件用的是三电阻采样还是单电阻，Workbench 会自动带出来，别手改。
- PWM 频率这一项，云台电机一般 20 kHz 起步，低了有可闻噪声，高了开关损耗和采样窗口都吃紧。
- 生成工程，选目标 IDE，输出到纯英文路径。
- 编译、下载，然后回到 Workbench 打开串口 Dashboard。
关键参数先按保守值来，转起来之后再调：
| 参数 | 建议初值 | 说明 |
|---|---|---|
| PWM 频率 | 20 kHz | 云台电机常用，兼顾噪声和采样窗口 |
| 死区时间 | 按功率管手册，常见几百 ns | 设小了直通，设大了波形畸变 |
| 母线电压 | 按实际供电填 | 填错会导致过压/欠压误报 |
| 电流采样方式 | 跟随功率板 | 三电阻/单电阻由硬件决定，不能凭感觉选 |
| 速度环周期 | 1 ms | 与 PWM 中断解耦，先按默认 |
| 启动电流 | 额定电流的 30%～50% | 太大容易触发过流保护 |
Dashboard 里能看到状态机、母线电压、转速、电流波形，还有一排控制按钮。第一次点启动，电机应该是先对齐、再开环拖到一定转速、然后切闭环，整个过程一两秒。如果卡在某一步，Dashboard 上的状态会停在对应位置，这比在代码里打断点直观得多。
3.2 Customer Board：芯片不在列表里怎么办
Workbench 的芯片型号列表是有限的，G474RET6 这类具体型号不一定直接出现在下拉框里，实际项目又不可能永远用 Demo 板。这时走 Customer Board 路径：新建工程时板子类型选自定义，功率板和电机仍然可以从现有型号里挑，只有主控需要自己配。
具体操作对应 Workbench 的六步向导：
- 配置电机和功率板参数。功率板选 X-Nucleo-IHM16M1，电机选 GBM2804H-100T 或参数最接近的型号，额定电流、极对数、相电阻这些按资料填。
- 芯片选择。列表里找不到 G474RET6，就选同系列里封装、外设最接近的型号做参考，比如同为 G4 系列、定时器和 ADC 资源相近的型号，后面在 CubeMX 里再改回真实型号。
- 数字端口配置。三相互补 PWM 占 Timer 的六路输出，使能脚、故障脚、串口收发脚都要一一对应。
- 模拟端口配置。相电流两到三路、母线电压一路、温度一路，分别落到 ADC 的注入组或规则组。
- 检查时钟树和中断优先级，电流采样中断的优先级必须高于串口和低速任务。
- 生成工程，导出到 IDE。
这里最容易出错的是第 2 步。参考型号选错，Workbench 生成的引脚分配和你实际板子对不上，后面在 CubeMX 里改起来就是灾难。我的做法是先把 G474RET6 的数据手册引脚复用表打开，把要用到的定时器通道、ADC 通道列成一张表，再回 Workbench 里挑一个引脚分布最接近的参考型号。这张表可以直接当核对清单用：
| 信号 | 外设资源 | 备注 |
|---|---|---|
| PWM 三相六路 | TIM1 CH1/2/3 及互补通道 | 必须成对，死区由定时器硬件插入 |
| 相电流采样 | ADC 注入组，由 TIM1 触发 | 触发点要落在下桥臂导通中点 |
| 母线电压 | ADC 规则组，低速轮流采样 | 分压比按实际电阻算 |
| 调试串口 | USART2 | Nucleo 板载虚拟串口一般走这路 |
| 编码器/Hall | TIM3 或 TIM4 编码器模式 | 有传感方案才需要 |
3.3 数字端口和模拟端口的配置逻辑
数字端口这块，核心是把「谁控制谁」理清楚。三相互补 PWM 是定时器硬件直出的，Workbench 生成的代码只是配置寄存器和启动；使能脚和故障脚是普通 GPIO，故障脚一般配成外部中断，过流信号一来立刻进中断关 PWM，这条路径必须比任何软件轮询都快。串口负责和上位机通信，波特率通常 115200，Dashboard 连接不上时先查这一项。
模拟端口的坑更多。相电流采样讲究采样时刻，必须落在下桥臂导通的中间，早了有开关振铃，晚了电流已经换向。Workbench 里配的触发源和采样窗口就是干这个的，改之前先想清楚硬件拓扑。母线电压和温度这两路对实时性要求低，放规则组轮流采就行，但分压电阻的比值一定要按实际板子填，填错的表现是 Dashboard 上电压显示正常、一启动就报过压，很容易误判成硬件问题。
生成工程之后别急着改代码，先在 Workbench 里把电机跑起来，确认参数和硬件匹配。这一步过了，再谈往 CubeMX 移植。
4. 移植到 CubeMX：把 Workbench 工程接进自己的 G474RET6
4.1 工程结构对照
Workbench 生成的工程大致分三块：MotorControl/放应用层和状态机，MCSDK 库目录放电机库，Inc/Src放外设初始化。CubeMX 生成的工程是另一套结构：Core/放 main 和外设初始化，Drivers/放 HAL。移植的本质是把前者塞进后者的框架里，让 CubeMX 管引脚和时钟，让 MCSDK 管算法。
先做一次目录对照，心里有数再动手：
| Workbench 侧 | CubeMX 侧 | 处理方式 |
|---|---|---|
| 外设初始化代码 | Core/Src/main.c里的 MX_xxx_Init | 以 CubeMX 为准，Workbench 的初始化删掉 |
| 电机控制任务 | 主循环或定时任务 | 保留，挂到 CubeMX 的 main 循环里 |
| 中断服务函数 | stm32g4xx_it.c | 合并，注意不要重复定义 |
| 库文件和头文件路径 | 工程 include 配置 | 原样搬过去 |
4.2 在 CubeMX 里对齐定时器、ADC 和串口
新建 CubeMX 工程，芯片选 G474RET6，时钟配到外部晶振加 PLL，主频按芯片能力拉满。然后逐个外设对齐：
/* TIM1：三相互补 PWM，中心对齐模式，死区由 BDTR 配置 */ htim1.Instance = TIM1; htim1.Init.CounterMode = TIM_COUNTERMODE_CENTERALIGNED1; htim1.Init.Period = 4249; /* 170MHz / (2*20kHz) - 1，对应 20kHz PWM */ htim1.Init.RepetitionCounter = 0; /* 死区时间：按功率管和驱动器的开通关断时间留余量 */ sBreakDeadTimeConfig.DeadTime = 42; /* 单位是定时器时钟周期，按实际换算 */ sBreakDeadTimeConfig.AutomaticOutput = TIM_AUTOMATICOUTPUT_ENABLE; /* ADC 注入组：由 TIM1 的更新事件触发，采两相电流 */ sConfigInjected.TriggerSource = ADC_EXTERNALTRIGINJEC_T1_TRGO; sConfigInjected.InjectedNbrOfConversion = 2;这段配置里三个参数值得展开。Period决定了 PWM 频率，170 MHz 主频、中心对齐模式下实际频率是170M / (2 * (Period+1))，算出来 20 kHz 就对了；改频率的时候死区也要跟着重算，因为死区寄存器的单位是定时器时钟周期。DeadTime设小了上下桥臂直通，模块当场冒烟，设大了输出波形畸变、低速时电流纹波明显。TriggerSource选定时器更新事件，是为了让采样点固定在 PWM 周期里的确定位置，这是电流环稳定的前提。
串口这边，USART2 配 115200、8N1，中断优先级排在电流采样之后。引脚按板子实际连接来，Nucleo 板载虚拟串口一般是 PA2/PA3，用别的板子要照原理图核。
生成代码后，把 MCSDK 的库目录和头文件路径加进工程，把MotorControl相关源文件拷进Core/Src同级目录，再在main.c里按顺序调用初始化。顺序不能乱：先 HAL 初始化，再外设初始化，最后电机控制初始化。
4.3 用 mc_api.c 接管电机控制
工程跑起来之后，控制电机就不需要碰 Workbench 了，直接调 API。最常用的几个函数都在mc_api.c里：
#include "mc_api.h" /* 上电后在 MX_MotorControl_Init() 之后调用，先确认状态机处于 IDLE */ void Motor_Startup(void) { /* 速度单位是 0.1Hz 的电气频率，不是机械转速；600 表示 60Hz 电气频率 */ MC_ProgramSpeedRampMotor1(600, 1000); /* 目标速度, 斜坡时间 ms */ MC_StartMotor1(); } /* 主循环里必须周期调用，间隔要稳定，建议挂 1ms 定时任务 */ void Motor_Loop(void) { MC_RunMotorControlTasks(); /* 状态机：IDLE / START / RUN / STOP / FAULT_NOW / FAULT_OVER */ if (MC_GetSTMStateMotor1() == FAULT_NOW) { uint16_t faults = MC_GetOccurredFaultsMotor1(); /* 读故障码定位原因 */ MC_AcknowledgeFaultMotor1(); (void)faults; } }三个要点。第一，速度单位是 0.1 Hz 的电气频率，写 600 是 60 Hz 电气频率，换算成机械转速要除以极对数再乘 60，很多人第一次调速度觉得「怎么这么慢」就是卡在这。第二，MC_RunMotorControlTasks()是状态机的心跳，必须周期调用且间隔稳定，放在主循环里如果被串口打印阻塞，表现出来就是启动失败或者转速抖动。第三，故障不能只清除不记录，MC_GetOccurredFaultsMotor1()返回的是位掩码，过流、过压、欠压、过热各占一位，把它打到串口上，排查效率比盲猜高一个量级。
接管之后，速度给定可以来自串口命令、电位器 ADC 或者上层协议，Workbench 的 Dashboard 就退化成调试工具，量产固件里不需要带。
5. 常见问题排查：电机不转、串口不通、电流采样漂移的坑
5.1 编译过了但电机纹丝不动
现象：程序下载成功，串口有输出，调MC_StartMotor1()之后电机没有任何反应，Dashboard 状态停在 IDLE 或者一闪就回 IDLE。
原因通常是启动条件没满足。MCSDK 的状态机在进入 START 之前会检查母线电压、温度、故障标志，任何一项不在范围内都直接拒绝启动。另一个常见原因是速度给定为 0，MC_ProgramSpeedRampMotor1的第一个参数没设或者设成了 0，状态机启动后立刻判定无速度指令而退出。
解决：先把MC_GetOccurredFaultsMotor1()的返回值打出来，非零就按位查手册；再确认启动前调用了速度斜坡函数且目标值大于最小启动速度。还不行就看母线电压采样值，分压比填错导致读数为 0，状态机一样不启动。
5.2 串口 Dashboard 连不上
现象：Workbench 点连接没反应，或者连上之后数据全是 0。
原因分三层：物理层没通、波特率不对、协议没跑起来。物理层看设备管理器里虚拟串口在不在，不在就是 ST-LINK 驱动问题；波特率默认 115200，改过 CubeMX 里的配置而 Workbench 没跟着改，就通不了；协议层是 MCSDK 的串口任务没被调度，主循环里漏了对应的处理函数。
解决：先用串口助手发一条命令看有没有回显，有回显说明物理层和波特率都对，问题在协议；没回显就倒回去查线和驱动。这一步能快速把问题范围砍一半。
5.3 电流采样零漂，电机低速抖动
现象：电机能转，但低速时抖动明显，Dashboard 上相电流波形不以零为中心，静止时也有一个固定偏置。
原因：运放和 ADC 的零点偏置没有校准。三电阻采样方案里，每相的运放偏置电阻有误差，加上 ADC 自身的偏移，静止时读数不是严格的中间值。MCSDK 有上电校准流程，但如果校准期间电机没静止、或者校准被跳过，偏置就会带进闭环。
解决：确保上电校准阶段电机完全静止，功率级使能但不出 PWM；校准完成后读一次静止电流值确认在零附近。偏置大的通道可以在配置里手动补偿，但先排除硬件问题，比如采样电阻虚焊。
5.4 一上电就过流保护
现象：点启动瞬间就报过流，电机只是「咯噔」一下。
原因：多数是 PWM 互补极性和功率管驱动不匹配，或者死区设得太小导致直通。也可能是母线电压参数填得比实际高很多，电流环算出来的占空比一上来就饱和。
解决：先用示波器看三相互补 PWM 波形，确认上下桥臂不会同时导通，死区时间够不够；再核对 Workbench 和 CubeMX 里的母线电压、电流采样增益是否一致。这类问题不要靠改保护阈值绕过，阈值放宽了下次就是炸管。
5.5 移植后引脚全乱
现象：Workbench 里跑得好好的工程，搬到 CubeMX 重新生成之后电机不转，或者转起来方向反了。
原因：参考型号选错导致引脚映射不一致，重新生成时 CubeMX 按自己的配置覆盖了原本的分配。
解决：移植前把引脚表打印出来逐项核对，特别是定时器通道和 ADC 通道；方向反了不用改硬件，交换任意两相 PWM 输出或者在 API 里把速度取负即可。生成代码后养成 diff 一遍外设初始化文件的习惯。
6. 进阶：先用 MotorProfiler 把电机参数测准，再谈调参
很多人跳过参数辨识直接调 PI，调半天调不好，回头发现电机的相电阻、电感、反电动势常数全是估的。MCSDK 里带的 MotorProfiler 就是干这个的：它在低速下注入小信号，测出 Rs、Ls 和反电动势常数，直接填进工程配置。用之前确认两件事：电机空载、母线电压稳定。测量过程中电机会轻微抖动，属于正常现象。
测完把参数存成配置文件，以后同型号电机直接导入。下面这段脚本用来记录启动过程的转速和电流，方便判断参数是否合理：
import serial, time, csv # 串口参数要和固件里一致，命令格式按自己固件的协议改 ser = serial.Serial("COM7", 115200, timeout=0.1) rows = [] t0 = time.time() ser.write(b"start\n") while time.time() - t0 < 5.0: # 采 5 秒 line = ser.readline().decode(errors="ignore").strip() if not line: continue try: speed, current = [float(x) for x in line.split(",")] except ValueError: continue # 跳过非数据行 rows.append((round(time.time() - t0, 3), speed, current)) with open("startup.csv", "w", newline="") as f: csv.writer(f).writerows(rows) ser.close()脚本只管收数据和落盘，重点在怎么看结果：启动阶段电流应该有一个明显的爬升然后回落到稳态值，转速曲线平滑上升没有台阶；如果电流一直顶在上限，说明启动电流或者速度环增益给大了；如果转速上不去还来回振荡，大概率是极对数填错或者速度单位没换算。
我一般会把这条曲线和 Dashboard 上的波形对一遍，两边一致才认为数据可信。有一次测出来反电动势常数明显偏大，查了半天发现是极对数按 7 对填的，实际电机是 11 对，改了之后速度环一次就调顺了。从那以后我每次换电机，都强制先跑一遍 MotorProfiler，再拿串口曲线做二次确认，绝不靠「看着差不多」直接上闭环。希望帮到你。
本文还有配套的精品资源，点击获取
