如何把SguanFOC移植到你的MCU上:跨平台移植指南与用户接口函数完整清单
如何把SguanFOC移植到你的MCU上:跨平台移植指南与用户接口函数完整清单
SguanFOC 是一款纯 C 语言的 PMSM 电机磁场定向控制(FOC)开源库,MIT 协议免费商用,覆盖 ARM、DSP 及任何支持 C 语言的 MCU。它从坐标变换、PID/LADRC 控制器到 SVPWM 调制全部内置,你只需填好用户接口函数,就能在几分钟内让电机闭环运转。本文给出完整的跨平台移植步骤和全部用户接口函数清单,是 SguanFOC 移植的实用参考指南。
先获取源码(git 方式):
git clone https://gitcode.com/gh_mirrors/sg/SguanFOC_Library
一、3 分钟看懂 SguanFOC 移植逻辑
SguanFOC 的移植思想很简单:库负责算法,你负责硬件。库与硬件之间只隔一层薄薄的用户接口,全部集中在 UserData_*.h 文件里:
移植只有 4 步:
| 步骤 | 做什么 | 涉及文件 |
|---|---|---|
| ① 选版本 | 按 MCU 有无 FPU、有无传感器选库 | 5 个版本目录任选其一 |
| ② 拷源码 | 把库的 .c/.h 全部加入工程编译 |
库目录内所有文件 |
| ③ 填接口 | 在用户接口文件里对接 ADC、PWM、编码器、串口 | UserData_Function.h/UserData_Function.h) |
| ④ 挂钩子 | 把 4 个主循环函数挂进你的中断/主循环 | SguanFOC.c/SguanFOC.c) |
硬件上建议参考作者开源的 CH32V3 机器人关节驱动板(三相电流采样 + 6 路 PWM + 母线电压检测),接口定义可直接对照:
二、先选对版本:5 个 FOC 库怎么选
仓库内按难度和精度划分了 5 个版本,选错版本是移植失败的第一大原因:
| 版本目录 | 定位 | 适用 MCU | 传感器方案 |
|---|---|---|---|
SguanFOC库v3.0.0(有感foc,浮点运算,初阶)/ |
有感入门 | Cortex-M 带 FPU(F4/H7 等) | 高精度编码器 |
SguanFOC库v3.0.1(有感foc,Q31定点,初阶)/ |
有感入门 | 无 FPU 的 32 位 MCU(M4 无 FPU、GD32 等) | 高精度编码器 |
SguanFOC库v3.1.0(无感foc,浮点运算,进阶)/ ⭐推荐 |
无感全速域 | Cortex-M 带 FPU | 霍尔 / 无感(HFI+SMO/NLFO) |
SguanFOC库v3.1.1(无感foc,Q31定点,进阶)/ |
无感全速域 | 无 FPU 的 32 位 MCU | 霍尔 / 无感 |
SguanFOC库v4.0.0(高度自由模块化foc,终阶)/ |
高度模块化、最多 6 电机 | 算力较强的 FPU MCU | 任意,自由组网 |
💡 新手建议:从 v3.1.0(浮点) 入手,算法最全、注释最详细;v4.0.0 的模块化接口更优雅,适合作为量产项目的最终架构。
硬件接口布局可对照官方硬件说明图:
三、v3.x 用户接口函数完整清单(核心)
v3.0.0 / v3.0.1 / v3.1.0 / v3.1.1 四个版本共用同一套接口,全部定义在 UserData_Function.h/UserData_Function.h) 中。每个函数都有示例注释,照着填即可:
| # | 函数名 | 作用 | 填写要点 |
|---|---|---|---|
| 1 | User_Initial_Init() |
上电即执行的初始化 | 启动 PWM 定时器中断、串口 DMA 接收 |
| 2 | User_StartMotor_Init() |
收到启动信号后才执行 | 使能栅极驱动 SD 引脚、开启 PWM 输出、编码器计数清零 |
| 3 | User_Delay(ms) |
延时对接 | 填 HAL_Delay() 或 SysTick 延时 |
| 4 | User_ReadADC_Raw(Current_CH) |
电流 ADC 原始值 | 通道 0→AB 相、1→AC 相、2→BC 相,返回 0~4095(12bit) |
| 5 | User_Encoder_ReadRad() |
编码器角度(0~2π rad) | 有感模式必填;霍尔/无感模式返回 0 即可 |
| 6 | User_Encoder_ReadHall(CH) |
三霍尔电平读取 | 霍尔模式必填,CH=0/1/2 读 UVW 三线 |
| 7 | User_PwmDuty_Set(Du, Dv, Dw) |
设置三相 PWM 占空比 | __HAL_TIM_SET_COMPARE() 写 3 路比较寄存器 |
| 8 | User_VBUS_DataGet() |
母线电压(滤波后) | 不用则返回 -9999.0f |
| 9 | User_Temperature_DataGet() |
驱动器温度 | 不用则返回 -9999.0f |
| 10 | User_CorrespondSet(ch, size) |
串口/CAN 发送对接 | 填 HAL_UART_Transmit() |
最关键的三个函数示例(约等于"硬件三件套"):
// ① 读电流 ADC 原始值
static inline int32_t User_ReadADC_Raw(int32_t CH) {
switch (CH) {
case 0: return (int32_t)ADC_InjectedValues[1]; // AB相
case 1: return (int32_t)ADC_InjectedValues[2]; // AC相
}
return 0;
}
// ② 写 PWM 占空比
static inline void User_PwmDuty_Set(uint32_t u, uint32_t v, uint32_t w) {
__HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_1, u);
__HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_2, v);
__HAL_TIM_SET_COMPARE(&htim1, TIM_CHANNEL_3, w);
}
// ③ 读编码器电气角度
static inline float User_Encoder_ReadRad(void) {
return Encoder_GetRad(); // 换算成 0~2π
}
其余参数在 4 个配置头文件中填写:
- 控制模式与算法开关:UserData_Config.h/UserData_Config.h) —
Define_Run_Mode宏选 0~18 共 19 种控制模式(VF 开环 → 三环伺服 → 全速域无感) - 电机物理参数(极对数、Rs、Ld/Lq、磁链):
UserData_Motor.h - 控制器 PID/LADRC 参数:
UserData_Parameter.h - 状态机回调与指令处理:UserData_Status.h/UserData_Status.h)、
UserData_UserControl.h
四、4 个主循环入口:如何挂进中断
库只暴露 4 个入口函数,挂到对应位置即可(以 v3.1.0 为例):
// 你的 main()
int main(void) {
MCU_Init();
while(1) {
SguanFOC_main_Loop(); // 主循环:上电初始化 + 数据收发
}
}
// PWM 定时器中断(16kHz~20kHz,高优先级)
void TIM1_BRK_UP_IRQHandler(void) {
SguanFOC_High_Loop(); // 电流环 + 角度计算 + SVPWM
}
// 1ms 定时器中断(1kHz,中优先级)
void TIM2_IRQHandler(void) {
SguanFOC_Low_Loop(); // 状态机切换 + 故障保护
}
// 串口接收中断
void USART1_IRQHandler(void) {
SguanFOC_Printf_Loop(Sguan_PrintfBuff, Size); // 上位机指令解析
}
| 入口函数 | 调用位置 | 频率 | 内部任务 |
|---|---|---|---|
SguanFOC_main_Loop() |
while(1) | 最低 | 上电初始化、状态机启动、数据打印 |
SguanFOC_High_Loop() |
PWM 中断 | 16~20 kHz | 电流环 PID、坐标变换、SVPWM |
SguanFOC_Low_Loop() |
1ms 定时器 | 1 kHz | 电机状态机、过流/过压保护 |
SguanFOC_Printf_Loop() |
串口中断 | 不定 | JustFloat 协议解析(AO=16.8? 格式) |
⚠️ 移植铁律:
High_Loop的中断频率必须与 PWM 频率一致,且 ADC 注入采样要配在 PWM 中央对齐点触发,否则电流采样相位全错。
五、v4.0.0 模块化版:驱动层接口与回调清单
v4.0.0 把接口改造成"驱动层 + 回调层"双层结构,支持最多 6 台电机(sguanfoc[CONFIG_MOTOR] 实例数组),适合多轴机械臂/关节项目。
① 驱动层——在 UserData_Driver.h/UserData_Driver.h) 中声明,UserData_Driver.c 中实现:
| 函数 | 作用 |
|---|---|
driver_read_tick() |
读系统时基(ms 级 tick) |
driver_read_vbus(CH) |
读第 CH 台电机母线电压 |
driver_read_ibus(CH) |
读母线电流 |
driver_read_temp_motor(CH) |
读电机温度 |
driver_read_temp_driver(CH) |
读驱动器温度 |
driver_read_temp_pcb(CH) |
读 PCB 温度 |
CH 用 MOTOR_ONE ~ MOTOR_SIX 宏区分多电机通道。
② 运行循环回调——填在 UnitLib_main.c/UnitLib_main.c):
- 状态入口:
main_standby_init/main_ready_init/main_initializing_init/main_goinit0_angle_init(角度对齐)/main_goinit1_current_init(电流初始化) - 高频任务:
main_high_loop_one~main_high_loop_six(每电机一个) - 低频任务:
main_high_loop/main_low_loop(状态机数据填充 +motorstatus_loop())
③ 状态机回调——UnitLib_Status.c/UnitLib_Status.c) 提供 17 个故障/运行状态钩子:
status_standby_loop、status_ready_loop、status_increasing_loop(加速中)、status_hold_loop(稳速)、status_overvoltage_loop、status_overcurrent_loop、status_overtemp_motor_loop、status_stuck_loop(堵转)、status_fault_loop(故障)等,方便做故障灯、急停逻辑。
④ 指令处理回调——UnitLib_UserControl.c/UnitLib_UserControl.c):
usercontrol_motor(启停)、usercontrol_speed、usercontrol_position、usercontrol_id、usercontrol_iq、usercontrol_ud、usercontrol_uq,每个回调带 float value 参数,直接对接你的上位机/CAN 指令。
⑤ 模块裁剪——UnitLib_Config.h/UnitLib_Config.h) 里 38 个 CODE_DEFINE_* 宏可自由开关 50+ 个算法模块(Transfer1~5 传递函数、PID、LADRC、SMC、PLL、LPF/HPF/BPF、HFI、SMO、NLFO、DOB、SVPWM/SPWM、单电阻采样等),Sguan_Transfer.h/Sguan_Transfer.h) 提供全部模块接口,用不到的模块设为 0 即可减小代码体积。
六、运行控制 API:几行代码操控电机
v3.x 通过 Sguan 全局结构体指针控制电机,API 直观到可以背下来:
| API | 功能 | 适用模式 |
|---|---|---|
Sguan.Func_Start() |
启动电机 | 全部 |
Sguan.Func_Stop() |
停止电机 | 全部 |
Sguan.Func_Set_Velocity(16.8f) |
设定转速 | 速度/位置环 |
Sguan.Func_Set_Position(26.8f) |
设定位置 | 三环伺服 |
Sguan.Func_Set_Iq(2.68f) |
设定 Q 轴电流 | 力矩控制 |
Sguan.Func_Set_Uq(1.68f) |
设定 Q 轴电压 | 电压开环 |
Sguan.Func_SetTXdata(0, Sguan.status) |
推送调试数据 | 配合上位机 |
内置的 PID 调节器原理可对照 Simulink 模型图理解(Sguan_PID.png):
七、移植避坑清单 🛠️
- FPU 匹配:浮点版务必在带 FPU 的 MCU 上编译,否则
float运算走软浮点,20kHz 电流环可能跑不完。 - PWM 与 ADC 对齐:注入采样窗口开在中央对齐点,
User_PwmDuty_Set与 ADC 触发共用同一 PWM 定时器。 - 编码器零位:
User_Encoder_ReadRad()返回的 0 必须对应电机 d 轴,否则用 UserData_Motor.h 中的偏移量校准。 - 电流方向:单电阻/双电阻采样的通道号(
Current_Num)必须与硬件一致,负号方向在current_dir0/1配置。 - 定点标幺化:Q31 定点版所有参数已按标幺值(pu)设计,母线电压、采样电阻等基值照
UserData_Motor.h注释填写即可,不要代入 SI 单位。 - 状态标志位:
High_Loop内部自带 PWM 计算看门狗,不要在Low_Loop中加长延时阻塞 1kHz 周期。
八、延伸阅读与配套资料
- 📖 完整 API 手册(含全部参数说明):Sguan使用说明书.pdf
- 📊 算法原理图(Simulink 开源模型):配套Simulink模型开源②[算法原理图]/ — SMO、NLFO、HFI、LADRC、PLL 等 14 张
- 🔧 开源硬件(嘉立创打板文件 + 原理图):【打板文件】Gerber_PCB_SguanFOC.zip/【打板文件】Gerber_PCB_SguanFOC.zip)
- 📄 中文主文档:README.md
按这份清单逐项填完 UserData_Function.h,编译通过、电机转起来,你的 SguanFOC 移植就成功了——剩下的工作只是调参。



