如何把SguanFOC移植到你的MCU上:跨平台移植指南与用户接口函数完整清单

原创2026-10-15 11:50:301,879 阅读
文章标签:嵌入式机器人

如何把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 文件里:

SguanFOC电机FOC控制库代码框架与模块包含关系图

移植只有 4 步:

步骤 做什么 涉及文件
① 选版本 按 MCU 有无 FPU、有无传感器选库 5 个版本目录任选其一
② 拷源码 把库的 .c/.h 全部加入工程编译 库目录内所有文件
③ 填接口 在用户接口文件里对接 ADC、PWM、编码器、串口 UserData_Function.h/UserData_Function.h)
④ 挂钩子 把 4 个主循环函数挂进你的中断/主循环 SguanFOC.c/SguanFOC.c)

硬件上建议参考作者开源的 CH32V3 机器人关节驱动板(三相电流采样 + 6 路 PWM + 母线电压检测),接口定义可直接对照:

SguanFOC开源硬件CH32V3驱动板PCB板示意图

二、先选对版本: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 的模块化接口更优雅,适合作为量产项目的最终架构。

硬件接口布局可对照官方硬件说明图:

SguanFOC开源硬件接口定义与接线说明图

三、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):

SguanFOC内置PID电流环与转速环闭环控制原理图

七、移植避坑清单 🛠️

  1. FPU 匹配:浮点版务必在带 FPU 的 MCU 上编译,否则 float 运算走软浮点,20kHz 电流环可能跑不完。
  2. PWM 与 ADC 对齐:注入采样窗口开在中央对齐点,User_PwmDuty_Set 与 ADC 触发共用同一 PWM 定时器。
  3. 编码器零位:User_Encoder_ReadRad() 返回的 0 必须对应电机 d 轴,否则用 UserData_Motor.h 中的偏移量校准。
  4. 电流方向:单电阻/双电阻采样的通道号(Current_Num)必须与硬件一致,负号方向在 current_dir0/1 配置。
  5. 定点标幺化:Q31 定点版所有参数已按标幺值(pu)设计,母线电压、采样电阻等基值照 UserData_Motor.h 注释填写即可,不要代入 SI 单位。
  6. 状态标志位:High_Loop 内部自带 PWM 计算看门狗,不要在 Low_Loop 中加长延时阻塞 1kHz 周期。

八、延伸阅读与配套资料

按这份清单逐项填完 UserData_Function.h,编译通过、电机转起来,你的 SguanFOC 移植就成功了——剩下的工作只是调参。

登录后查看全文
SguanFOC_Library