如何用SguanFOC在5分钟让PMSM电机转起来：新手快速上手完整指南

• 嵌入式
• 硬件开发
• 机器人

刚拿到一台PMSM无刷电机，不知道如何搭建磁场定向控制（FOC）方案？SguanFOC 是一款MIT协议开源的纯C语言FOC电机控制库，集成了SVPWM、有感/无感全速域控制、PID与LADRC控制器，支持ARM、DSP等任意C语言MCU。本文带你按6个步骤，在5分钟内完成配置，让电机闭环旋转起来。

1. 先认识SguanFOC：一个库解决所有FOC难题

SguanFOC 提供19种控制模式、4种控制算法（PID / LADRC / SMC / STA）、3种无感观测器（HFI / SMO / NLFO），从开环强拖到伺服级三环闭环全覆盖：

📌 完整API文档见 Sguan使用说明书.pdf

仓库内按难度分级提供了4个版本，新手建议从初阶开始：

2. 一分钟看懂库文件结构

库的架构非常清晰：核心框架 + 子模块解耦 + 用户配置接口。所有算法（PID、PLL、SVPWM、LADRC、HFI、SMO、NLFO等）都作为独立模块存在，通过 Sguan_Config.h/Sguan_Config.h) 宏开关组合，你只需要填写UserData_*.h系列文件即可。

👉 你作为新手只需要关心两类文件：

• 用户配置接口（必改）：UserData_Function.h/UserData_Function.h)（硬件接口）、UserData_Config.h/UserData_Config.h)（模式选择）、UserData_Motor.h/UserData_Motor.h)（电机参数）、UserData_Parameter.h/UserData_Parameter.h)（控制器参数）
• 核心框架（只读）：SguanFOC.c/SguanFOC.c)、Sguan_PID.h/Sguan_PID.h) 等算法模块

3. 填写硬件接口：UserData_Function.h

这是唯一需要"对接硬件"的文件，共10个接口函数，每个都有注释说明。最核心的5个：

1. User_Initial_Init—— 上电即执行，如开启定时器中断、串口DMA接收
2. User_ReadADC_Raw—— 返回电流采样的ADC原始值（如12位为0~4095）
3. User_PwmDuty_Set—— 设置U/V/W三相PWM占空比
4. User_Encoder_ReadRad—— 编码器角度（0~2π），霍尔/无感模式可留空
5. User_CorrespondSet—— 串口/CAN发送，用于上位机调试

每个函数里都附有示例代码（以注释形式），照抄改成自己的HAL库调用即可，详见 UserData_Function.h/UserData_Function.h#L24-L166)。

4. 选择控制模式 + 填电机参数

第一步：选模式。在 UserData_Config.h/UserData_Config.h#L29) 中修改一行宏定义：

#define Define_Run_Mode 0 // 0->开环强拖，先让电机转起来

第二步：填参数。在 UserData_Motor.h/UserData_Motor.h#L12-L74) 中填写：

• 电机物理参数：极对数Poles、母线电压VBUS、电阻/电感/磁链
• 量化参数：ADC精度、采样电阻、运放增益（决定电流环精度）
• 安全参数：过流/过温/欠压阈值（过流保护，先从小电流起步）

第三步：控制器原理。库内电流环默认采用PI控制，结构如下（开源Simulink模型可对照算法细节）：

速度环可选PID/LADRC/SMC/STA四种算法，同样在UserData_Config.h中用一个宏切换，零成本体验LADRC自抗扰控制的效果差异。

5. 调用4个核心函数，5分钟闭环启动

接入MCU只需要把4个函数放进对应的中断/主循环（伪代码，实际以你的外设命名为准）：

#include "SguanFOC.h" int main(void) { MCU_Init(); // 你的平台初始化 while(1) { SguanFOC_main_Loop(); // ① 初始化 + 串口收发 } } void TIM1_IRQHandler(void) { SguanFOC_High_Loop(); // ② PWM中断(10K~40KHz)：电流环+SVPWM } void TIM2_IRQHandler(void) { SguanFOC_Low_Loop(); // ③ 1KHz中断：状态机切换、故障保护 } void USART1_IRQHandler(void) { SguanFOC_Printf_Loop(buff, len); // ④ 串口调试指令解析 }

这就是全部！4个函数背后是完整的坐标变换、Park/Clarke、PID运算、SVPWM七段式调制和状态机管理，全部在 SguanFOC.c/SguanFOC.c#L2201-L2309) 中实现。

⚡新手避坑3条：

• 先开环（模式0/1）确认方向，电机正反转不对就改Motor_Dir/PWM_Dir方向位
• 开环强拖失败时，降低起始频率再试，并确认相序
• 闭环前先把Qcur_MAX过流限制设小，防止参数错误烧驱动

6. 上位机实时调试：串口即可调参

库内置 JustFloat 协议串口通信（Sguan_printf.c/Sguan_printf.c)），配合配套的QT电控上位机，可以直接在电脑端修改Uq、Iq、Speed、Position目标值，并实时查看转速、电流波形曲线。在 UserData_UserControl.h/UserData_UserControl.h) 中配置要上报的数据项即可，上位机获取方式见 Sguan电控上位机.txt。

7. 进阶：无感FOC全速域切换验证

如果你的项目要求去掉编码器，SguanFOC 提供 HFI（高频注入，低速域）→ SMO/NLFO（中高速域）的平滑切换，下图为真实硬件上 HFI 切 SMO 的实测曲线（黄色为无感观测转速，与编码器实测速度高度吻合）：

无感算法的Simulink原理图已全部开源，方便对照源码理解：Sguan_HFI.png、Sguan_SMO.png、Sguan_NLFO.png。

8. 配套开源硬件：CH32V3机器人关节PCB

如果你暂时没有开发板，仓库提供了基于CH32V3的开源硬件（圆形关节PCB），直接通过串口控制 Uq/Iq/Speed/Position，支持2208、4006、5010等常见无刷电机，适合机器人关节、机械臂等场景：

📦 硬件打板文件与例程代码在 Hardware硬件(制板文件和原理图)//)，MRS开发环境配置说明见 MRS软件下载地址.txt/MRS软件下载地址.txt)。

总结：从克隆到电机转动只需6步

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/sg/SguanFOC_Library
2. 按难度选一个库版本目录，拷入你的工程
3. 在UserData_Function.h对接ADC/PWM/编码器接口
4. 在UserData_Config.h选控制模式，UserData_Motor.h填电机参数
5. 主循环和中断中调用4个SguanFOC_xxx_Loop函数
6. 烧录、连上位机，先开环强拖，再切闭环 🎉

SguanFOC 采用 MIT 协议，个人和商用均免费（详见 LICENSE）。从简单调速到高性能伺服，它都能陪你一路调参到"丝滑运转"。

• 嵌入式
• 硬件开发
• 机器人