简介：这份 PDF 文档面向刚接触 STM32G4 系列、希望系统入门电机控制的嵌入式开发者和学生，围绕 ST 电机控制生态、MC SDK 与 CubeMX 的配合使用展开，重点解决从方案认知到 FOC 工程搭建、代码生成与移植的入门问题。压缩包内仅含 1 个 PDF 文件，大小约 3.64MB，便于在电脑或平板上直接查阅。内容以 STM32G4 为平台，梳理交流电机、直流有刷电机、PMSM、BLDC、步进电机等对象与控制方式，并借助 Motor Control Workbench 演示工程创建、Demo 板与功率板选择、电机参数配置，以及定时器、控制脚、串口、编码器和 Hall 信号等数字端口，电流、电压、温度等模拟端口的设置思路；同时说明如何结合 CubeMX 将电机控制代码移植到 STM32G474RET6 等未直接收录的芯片上，并给出串口控制、API 函数控制等运行调试入口。已有约 900 人学习，适合作为电机控制基础培训资料和动手实践前的参考。
1. 装 STM32G4 电机控制环境前：先分清 Demo 板、功率板和 MC SDK 的版本账
STM32 电机控制这件事，最容易翻车的不是 FOC 算法，而是装环境。我见过一块 NUCLEO-G474RET6 插着 X-NUCLEO-IHM16M1，CubeMX 却装在带中文的目录里，Workbench 里又选了 P-NUCLEO-IHM03 的默认工程，最后编译能过、烧录也能跑，电机一使能就报过流。对做 STM32G4 电机控制的人来说，装错版本、选错板型、漏配采样通道，比算法调参更耗时间。这套环境适合刚拿到 G4 控制板、准备跑第一套 FOC 的开发者，也适合从 Demo 板迁到自己板子的熟手。下面按我实际装机的顺序，把版本、安装、Workbench 生成、CubeMX 移植、排错和验证拆开写。
2. 安装清单：X-CUBE-MCSDK 5.x 与 STM32CubeMX v5.6 以上的版本搭配
装这套环境，第一步不是双击安装包，而是把版本账对平。STM32G4 电机控制涉及 CubeMX、G4 固件库、X-CUBE-MCSDK 或 X-CUBE-MCSDK-FUL、IDE、ST-LINK 驱动五块，任意一块版本偏了，后面生成工程时不一定立刻报错，往往拖到编译或烧录才暴露。我的习惯是先列一张表，把输入资料里给定的版本写死，再去装。
| 组件 | 输入给定版本/型号 | 装机时干什么 | 装错后的典型表现 |
|---|---|---|---|
| X-CUBE-MCSDK | 5.x，或 X-CUBE-MCSDK-FUL | 生成 FOC 工程、提供 mc_api.c 与电机控制库 | Workbench 打不开工程，或生成后缺电机参数文件 |
| STM32CubeMX | v5.6 以上，及 G4 固件库 | 改芯片、补引脚、装固件包 | 打开 .ioc 报版本不兼容，或生成代码缺 HAL 头文件 |
| ST-LINK | ST-LINK/V2 或 ST-LINK/V3 | 烧录与 SWD 调试 | 能编译不能下载，或下载后不运行 |
| IDE | IAR Embedded Workbench for Arm v8.x、Keil MDK v5.x、Atollic TrueSTUDIO 9.0.0 三选一 | 编译、下载、在线调试 | 打开工程缺器件包，链接阶段报错 |
| 固件库 | 与 CubeMX 配套的 G4 固件包 | 提供 HAL 与底层驱动 | 编译缺头文件，HAL 版本冲突 |
MCSDK 普通版和 FUL 版的取舍，我一般先装普通版跑通 Demo，等要改底层电流环或看库源码时再换 FUL。FUL 包更完整，排查底层问题时不用猜黑匣子；普通版装起来轻，适合先把 Workbench 和 CubeMX 的链路走通。CubeMX 不要追最新，v5.6 以上是底线，装完先把 G4 固件库补上，否则后面生成工程会提示找不到对应系列的支持包。
2.1 PC 侧软件版本与安装顺序
我装机按下面顺序走，不跳步。先装 CubeMX，再用 CubeMX 的包管理器装 G4 固件库，然后装 MCSDK，接着装 IDE，最后插 ST-LINK 装驱动。这个顺序的好处是 CubeMX 先占住路径，MCSDK 生成工程时能直接找到 CubeMX 和固件库；如果先装 IDE，Keil 或 IAR 的器件包有时会抢在 CubeMX 前面，导致后面打开工程缺器件。
- 安装 STM32CubeMX，路径选英文目录，例如
D:\STM32\STM32CubeMX。 - 打开 CubeMX，进入 Manage embedded software packages，安装 STM32G4 系列固件包。
- 安装 X-CUBE-MCSDK 5.x，路径同样不要带中文，例如
D:\STM32\X-CUBE-MCSDK。 - 安装 Keil MDK v5.x、IAR v8.x 或 Atollic TrueSTUDIO 9.0.0，三选一即可，不要三个都用来开同一个工程。
- 插上 ST-LINK/V2 或 V3，装驱动，在设备管理器里确认能看到调试器设备。
装完后先做一次路径检查。CubeMX 和 MCSDK 对中文路径很敏感，工程目录带中文时，生成代码可能卡住，或者生成到一半缺文件。下面这段 PowerShell 用来检查几个关键目录是否存在、是否含中文：
# CubeMX、固件库、MCSDK 的路径都不要带中文和空格 $roots = @( "D:\STM32\STM32CubeMX", "D:\STM32\STM32Cube\Repository", "D:\STM32\X-CUBE-MCSDK" ) $roots | ForEach-Object { if ($_ -match '[\u4e00-\u9fa5]') { Write-Host "含中文: $_" } elseif (Test-Path $_) { Write-Host "可用: $_" } else { Write-Host "未安装: $_" } }这段脚本里$roots换成你实际的安装目录，正则[\u4e00-\u9fa5]用来匹配中文，Test-Path判断目录是否存在。输出“含中文”的路径不要将就，直接换到英文目录重装；输出“未安装”的先确认是不是装到了别的盘。路径里空格也尽量少，有些老版本工具对空格的处理不如中文路径稳。
提示：CubeMX 安装路径、固件库仓库路径、MCSDK 工程路径三处都不要带中文。只改安装路径不够，工程目录也要英文。
2.2 控制板、功率板、电机型号对照
版本对平之后，第二步是对板型。输入资料里给了两套典型组合：一套是 P-NUCLEO-IHM03 电机控制套件，另一套是 NUCLEO-G474RET6 控制板加 X-NUCLEO-IHM16M1 功率板，再配 GBM2804H-100T 电机。前者在 Workbench 里有现成 Demo，后者往往要走 Customer Board。
| 场景 | 控制板 | 功率板 | 电机 | Workbench 选择 |
|---|---|---|---|---|
| 跑第一套 Demo | P-NUCLEO-IHM03 套件 | 套件自带功率板 | 套件配套电机 | 直接选 STM32G4 Demo 板 |
| 迁自己板 | NUCLEO-G474RET6，芯片 STM32G474RET6 | X-NUCLEO-IHM16M1 | GBM2804H-100T | Customer Board，选类似芯片做参考 |
P-NUCLEO-IHM03 是整套套件，Workbench 里选 STM32G4 Demo 板后，功率板和电机都能对应上，生成工程最省事。NUCLEO-G474RET6 加 X-NUCLEO-IHM16M1 这套，控制板和功率板是分开的，Workbench 的芯片列表里不一定有 STM32G474RET6，所以不能硬选一个不匹配的 Demo，得走 Customer Board，先选一个同系列、同档位的 G4 芯片做参考，再用 CubeMX 把芯片改成 STM32G474RET6。
这里最容易犯的错是“看着板子差不多就选”。P-NUCLEO-IHM03 的默认工程能跑，不代表接到 NUCLEO-G474RET6 加 X-NUCLEO-IHM16M1 上也能跑。功率板的电流采样、预驱使能脚、母线电压检测位置都可能不同，默认参数只能当起点，不能当答案。
2.3 安装路径、驱动和固件库的预检查
装完软件后，先别急着打开 Workbench 建工程。我一般做三件事：确认 CubeMX 能新建 G4 工程、确认 MCSDK 能启动、确认 ST-LINK 能被 IDE 识别。这三件事任何一件没通，后面生成 FOC 工程都会变成连环坑。
CubeMX 新建工程时选 STM32G4 系列，随便选一个 G4 芯片，能进入引脚配置界面就说明固件库装上了。MCSDK 启动后能看到 Motor Control Workbench 界面，说明安装路径和依赖没问题。ST-LINK 插上后，在 Keil 的 Debug 设置里能看到 ST-LINK，或者在 IAR 的下载选项里能识别，说明驱动通了。
固件库版本要和 CubeMX 配套。CubeMX 里装 G4 固件包时，选与当前 CubeMX 兼容的版本，不要手动往仓库里拷一个来路不明的包。MCSDK 生成工程时会调用 CubeMX 和固件库，版本不配套时，生成日志里可能只报一句“code generation failed”，看起来像玄学，实际是固件库路径或版本不对。
注意：ST-LINK/V2 和 V3 的驱动不要混装。设备管理器里看到黄色感叹号时，先卸掉旧驱动再装当前调试器对应的驱动。
3. 生成第一套 FOC 工程：Motor Control Workbench 里选 P-NUCLEO-IHM03 的完整步骤
环境装好之后，最快建立信心的方法是先用 P-NUCLEO-IHM03 跑一套 Demo。Workbench 的价值在于把电机参数、功率板参数、电流采样、PWM 定时器这些底层配置打包成图形化选项，生成一套能编译的 FOC 工程。先跑通这套，再去迁 STM32G474RET6，心里有底。
3.1 新建工程与 P-NUCLEO-IHM03 选择
打开 Motor Control Workbench，新建工程，选择 STM32G4 Demo 板，功率板选 P-NUCLEO-IHM03 套件对应的功率板，电机选套件配套电机。工程保存路径用英文，例如D:\STM32\Work\IHM03_Demo。保存后 Workbench 会进入配置界面，先不要改一堆参数，按默认配置生成一次，确认工具链是通的。
| Workbench 项 | 本例选择 | 检查点 |
|---|---|---|
| 板型 | STM32G4 Demo 板 | 选完能看到功率板和电机下拉框 |
| 功率板 | P-NUCLEO-IHM03 套件功率板 | 名称与手头套件一致 |
| 电机 | 套件配套电机 | 极对数、额定电流先按默认 |
| 工程路径 | 英文目录 | 不含中文和空格 |
| 生成目标 | CubeMX 工程加 IDE 工程 | 至少选一个你装好的 IDE |
生成后先检查三个关键文件：mc_api.c是 API 控制入口，mc_config.c存放电机和功率板参数，.ioc是 CubeMX 配置。少一个都说明生成不完整。下面这段命令在 Git Bash 或 WSL 里跑，用来快速确认：
# 生成后先看这三个文件是否齐全，缺一个就回 Workbench 重新生成 find ./IHM03_Demo -maxdepth 3 \( -name "mc_api.c" -o -name "mc_config.c" -o -name "*.ioc" \) -print-maxdepth 3只扫三层目录，避免全盘扫描；-name分别匹配 API 文件、参数文件和 CubeMX 配置文件。三个文件都在，再打开 IDE 编译。如果mc_api.c缺失，后面想用 API 函数控制电机就没有入口；如果.ioc缺失，CubeMX 改引脚时只能重建工程。
3.2 电机与功率板参数：默认配置不是万能
Demo 默认参数能跑套件电机，但迁移到自己板子时必须逐项核对。我一般先看电机极对数、额定电流、母线电压范围，再看功率板的电流采样电阻和运放增益。极对数填错，Dashboard 显示的转速会差一倍；电流采样增益填错，电机一使能就报过流；母线电压范围填窄，稍微降压就触发欠压保护。
| 参数项 | 从哪里来 | 填错的后果 |
|---|---|---|
| 电机极对数 | 电机铭牌或手册 | 转速显示和实际差倍数 |
| 额定电流 | 电机铭牌 | 限流点过高或过低 |
| 母线电压范围 | 功率板输入范围 | 欠压/过压误报 |
| 电流采样电阻与增益 | 功率板原理图 | 电流波形幅值不对，过流误报 |
| 编码器或 Hall | 电机与板子接口 | 启动失败或方向反 |
| PWM 死区 | 功率板预驱要求 | 上下桥直通风险 |
这里不要照抄 Demo。P-NUCLEO-IHM03 的参数只对那套套件有意义，换成 X-NUCLEO-IHM16M1 加 GBM2804H-100T 后，电流采样和预驱控制脚很可能不同。我的做法是先把电机铭牌和功率板原理图放桌上，Workbench 里每改一项就在图纸上对应确认一次，改完重新生成工程，不在一份工程上反复覆盖。
3.3 生成代码前的检查项：时钟、串口、调试口
生成代码前还有三个检查项：时钟树、串口、调试口。时钟不对，PWM 频率和 ADC 采样时序都会偏；串口没配，Workbench 的 Dashboard 连不上；调试口没留，后面烧录后不跑只能靠猜。
| 检查项 | 在 Workbench/CubeMX 看哪里 | 通过标准 |
|---|---|---|
| 系统时钟 | CubeMX 时钟树 | 与板子晶振和 PLL 配置一致 |
| PWM 定时器 | Workbench 功率板配置 | 三相互补通道已分配 |
| 串口 | Workbench 通信配置 | TX/RX 与板子调试串口一致 |
| SWD 调试口 | CubeMX Pinout | SWDIO、SWCLK 未被占用 |
| 电流采样 | Workbench 电流采样页 | 三路电流通道与原理图一致 |
串口这块容易忽略。Dashboard 的通信链路状态是验证 FOC 是否跑起来的最快窗口，串口 TX/RX 接反或者波特率不对，Dashboard 会一直显示未连接。插上 ST-LINK 和串口线后，可以先在系统里确认 COM 口：
# 插上 ST-LINK 和串口线后，先确认系统认到了 COM 口 Get-WmiObject Win32_SerialPort | Select-Object DeviceID, DescriptionDeviceID是 COM 号，Description是驱动名称。看不到 COM 口时先换线、换 USB 口、装驱动，不要急着改 Workbench 里的串口配置。看到 COM 口但 Dashboard 连不上，再回头核对波特率和 TX/RX 是否交叉。
4. 移植到 STM32G474RET6：用 CubeMX 补数字端口和模拟端口的配置顺序
Workbench 里芯片型号选择有限，实际项目常用 STM32G474RET6，这时候不能硬等 Workbench 支持，得用 Customer Board 加 CubeMX 移植。我的顺序是：Workbench 先生成一套参考工程，CubeMX 改芯片型号，补数字端口，补模拟端口，最后把电机参数文件合回去。顺序反了，引脚配置容易被覆盖。
4.1 Customer Board 模式与参考芯片选择
在 Workbench 里新建 Customer Board 工程，功率板选 X-NUCLEO-IHM16M1，电机选 GBM2804H-100T 或列表里最接近的型号，芯片先选一个同系列、同档位的 G4 做参考。参考芯片不要选差太远的型号，Flash、RAM、定时器数量差太多，生成出来的工程改起来更费劲。
| 步骤 | 操作 | 检查点 |
|---|---|---|
| 1 | Workbench 新建 Customer Board | 不选现成 Demo 板 |
| 2 | 功率板选 X-NUCLEO-IHM16M1 | 与手头功率板一致 |
| 3 | 电机选 GBM2804H-100T 或最接近型号 | 极对数、额定电流可后改 |
| 4 | 芯片选类似 G4 型号 | 同系列、同档位 |
| 5 | 生成工程 | 先能编译通过 |
| 6 | CubeMX 打开 .ioc 改芯片为 STM32G474RET6 | 改完重新生成代码 |
改芯片后先编译一次空工程。这一步只验证 CubeMX 生成的启动文件、时钟和 HAL 能过编译，不验证电机。空工程都过不了，先查固件库和 IDE 器件包，不要往下配引脚。
4.2 数字端口配置：Timer、控制脚、串口、编码器与 Hall
数字端口是移植里最费眼的部分。Timer 管脚要分配三相互补 PWM，控制脚要接预驱使能或故障脚，串口要留 TX/RX，有传感的控制还要配编码器 A/B/Z 或 Hall U/V/W。每个脚都按功率板原理图来，不要凭 Workbench 默认值照搬。
| 功能 | Workbench 对应项 | CubeMX 检查点 | 常见错 |
|---|---|---|---|
| 三相互补 PWM | 功率板 Timer 配置 | TIM 通道设为 PWM Generation，互补输出使能 | 只配了单路，没开互补 |
| 预驱使能/故障 | 控制脚配置 | GPIO 输出/输入模式与电平正确 | 使能脚极性反，电机不转 |
| 串口 | 通信配置 | Asynchronous，TX/RX 与调试口一致 | TX/RX 接反，Dashboard 不连 |
| 编码器 | 传感器配置 | TIM Encoder 模式或 GPIO 输入 | A/B 相接反，方向反 |
| Hall | 传感器配置 | GPIO 输入或 TIM Hall 模式 | 相序错，启动抖动 |
配置时先在 CubeMX Pinout 视图里把每个功能脚点出来，能标标签的标上，例如PWM_U、PWM_V、PWM_W、EN_GATE、UART_TX。标签不是给编译器看的，是给你自己后面查原理图用的。PWM 频率和死区时间按功率板预驱要求填，不要直接抄 Demo，预驱型号不同，死区不够会直通，死区太大会影响低速性能。
4.3 模拟端口配置：电流、电压、温度采样
模拟端口决定电机能不能安全跑。三路电流采样、母线电压采样、温度采样，少一路保护就少一层。CubeMX 里要把 ADC 通道、采样时间、触发源配好，电流采样通常要和 PWM 同步，电压和温度可以用规则通道慢采。
| 采样通道 | 作用 | CubeMX 设置 | 常见错 |
|---|---|---|---|
| 三相电流 | FOC 电流环输入 | ADC 注入或规则通道，触发源与 PWM 同步 | 采样时刻不对，电流波形畸变 |
| 母线电压 | 欠压/过压保护 | ADC 规则通道，分压比按原理图 | 分压比算错，保护点偏 |
| 温度 | 过温保护 | ADC 规则通道，NTC 分压 | NTC 参数填错，误报过温 |
电流采样是重点。采样电阻值和运放增益填错，FOC 的电流环根本没法收敛，表现是电机一使能就抖或者直接过流。我的做法是先不接电机，只给控制板和功率板上电，用 Dashboard 或调试变量看三相电流零点是不是在中间值附近，零点偏太多先查运放和 ADC 参考电压，不要急着调 PID。
4.4 从 Workbench 导出到 CubeMX 的目录合并顺序
移植时最容易翻车的动作是“整目录覆盖”。Workbench 生成的工程和 CubeMX 重新生成的工程各有各的时钟、引脚和启动文件，直接覆盖会把 CubeMX 改好的芯片配置冲掉。我一般先备份，再在 CubeMX 里改芯片和引脚，重新生成代码，最后只把电机参数相关的.c/.h合回去。
# 改芯片型号前先留一份可回退的工程副本 Copy-Item -Recurse .\MotorProject .\MotorProject_backup_$(Get-Date -Format yyyyMMdd_HHmm)Copy-Item -Recurse递归复制整个工程，$(Get-Date -Format yyyyMMdd_HHmm)在目录名里加时间戳，出问题时能退回上一版。备份不是形式，移植改芯片时一次覆盖就可能把能跑的工程弄丢，这份副本就是后悔药。
合并时先对比Core/Src和Core/Inc里哪些文件是 Workbench 电机参数、哪些是 CubeMX 生成的引脚初始化。引脚初始化以 CubeMX 为准，电机参数以 Workbench 为准，两边冲突时不要闭眼选一边，打开文件看宏定义和注释。合并完先编译，再烧录，不要编译和烧录一起上。
5. 常见问题排查：MCSDK 工程编译不过、烧录不跑、电机不转的五条记录
这几条是我在 G4 板子上反复翻车后记下来的血泪经验。现象看起来分散，原因大多集中在路径、版本、引脚和采样四件事上。每条按现象、原因、解决写，照着查比重新装一遍快。
5.1 编译与工程导入：中文路径、固件库、IDE 版本
现象一：CubeMX 生成代码卡住，或者生成完缺文件。原因通常是安装路径或工程路径带中文、空格，CubeMX 在写临时文件时失败。解决是把 CubeMX 安装目录、固件库仓库、工程目录全部换到英文路径，例如D:\STM32\Work\G474_FOC，工程名也用英文，重开 CubeMX 再生成。不要只改工程名，安装目录带中文一样会出问题。
现象二：Keil 打开工程提示找不到stm32g4xx.h，或者器件列表里没有 G4。原因一般是 CubeMX 里 G4 固件库没装完整，或者 Keil 没装 G4 器件包。解决是回 CubeMX 的 Manage embedded software packages 里确认 G4 固件包已安装，再在 Keil 里装对应 Device Family Pack，重新生成工程。IAR v8.x 打开高版本工程报不兼容时，不要硬改工程文件，回 CubeMX 选 IAR 重新生成，版本对不上时重生成比手修快。
5.2 烧录与运行：ST-LINK 连不上、烧录成功不跑、串口无输出
现象三：ST-LINK/V2 或 V3 连不上，IDE 报 no target connected。原因可能是驱动没装好、SWD 线序错、目标板没供电。解决是先换 USB 口，确认设备管理器里调试器正常，再查 SWDIO、SWCLK、GND 三根线，目标板单独供电。NUCLEO 板用 ST-LINK 供电时注意跳帽，功率板大电流场景最好单独给母线供电，不要只靠调试器。
现象四：烧录成功，复位后电机不转，串口也没输出。原因常见是下载后没复位运行、BOOT 引脚状态不对，或者串口 TX/RX 接反。解决是在 Keil 的 Flash Download 里勾 Reset and Run，检查 BOOT0 电平，按一次复位键；串口用前面那段 PowerShell 确认 COM 口，再核对 TX/RX 是否交叉。Dashboard 一直显示未连接时，先怀疑串口，不要先怀疑 FOC 算法。
5.3 采样与保护：电机一使能就过流、电流零漂、温度误报
现象五：电机一使能就报过流，Dashboard 电流波形顶满。原因多半是电流采样极性或增益填错，或者预驱使能脚配错。解决是先断开电机，只给控制板和功率板上电，看三相电流零点是否在中间值附近；再查采样电阻、运放增益和 ADC 参考电压；确认无误后用低母线电压、限流电源空载试启动。不要一上来就改电流环 PID，采样不对时调 PID 只会把问题藏得更深。
温度误报也按同样思路查。NTC 分压比、B 值、上拉电阻任一填错，常温就会报过温。先看 ADC 原始值，再对照原理图算温度，算出来和室温差太多就回头查参数。电机控制里保护参数宁可比实际保守一点，也不要为了跑得顺把过流和过温阈值放宽。
6. 装完怎么验证：用串口 Dashboard 和 mc_api.c 状态机确认 FOC 真的跑起来
装完环境、生成工程、烧录成功，不等于 FOC 跑通。我验证时按“先看通信、再看状态机、最后看电流”的顺序走，避免电机一转就掩盖了底层问题。先用低母线电压、限流电源、空载电机，Dashboard 通信链路状态能连上，再发启动命令。
| 验证项 | 通过标准 | 不过时先看哪 |
|---|---|---|
| 串口 Dashboard | 通信链路状态正常，能读到母线电压和温度 | COM 口、波特率、TX/RX |
| 状态机 | 启动后从 IDLE 进入 RUN，停止后回 IDLE | mc_api.c 调用、使能脚 |
| 三相电流 | 空载电流小且三相平衡，零点不偏 | 采样电阻、运放增益、ADC 触发 |
| 转速反馈 | 给定转速与实际转向一致 | 极对数、编码器/Hall 相序 |
| 保护 | 欠压、过流、过温阈值能触发 | 分压比、采样增益、NTC 参数 |
如果用 API 控制，可以在 `main.c
本文还有配套的精品资源，点击获取
