【离线版下载】SOEM + CiA 402 电机控制代码包:一套能直接编译运行的 EtherCAT 伺服驱动方案
【离线版下载】SOEM + CiA 402 电机控制代码包:一套能直接编译运行的 EtherCAT 伺服驱动方案
如果你想在 Windows 上用 EtherCAT 主站驱动一台符合 CiA 402 标准的伺服电机,又不想从零写主站协议,这个基于 SOEM(Simple Open EtherCAT Master)的代码包能让你少踩很多坑。它把「主站初始化 → 从站配置 → 进入 OP → CiA 402 使能 → 角度/速度控制」这条完整链路都串好了,你只需要换成自己的网卡和电机参数就能跑起来。下面按「它是什么 → 里面有什么 → 怎么准备 → 怎么跑通 → 参数怎么改 → 常见坑 → 如何贡献」的顺序,带你一步步上手。
这个代码包解决什么问题,适合谁用
这是一份面向 EtherCAT 主站 + CiA 402 伺服驱动 的电机控制工程,定位是「可运行的参考实现」而非抽象库。它适合下面几类人:
- 正在做运动控制 / 机器人关节 / 轴控,需要一台 PC 作为 EtherCAT 主站去控制伺服,想先有个能跑的骨架;
- 熟悉 C++ 但没写过 EtherCAT 主站协议,想对照代码看懂
ec_init、ec_config_init、OP 状态切换这些主站流程; - 需要研究 CiA 402 状态机(使能、故障复位、位置/速度模式切换)在真实驱动器上怎么走。
代码是 Windows 平台的:它使用 WinPcap 抓包、winmm 定时器作为周期循环(RT 线程),入口是 ConsoleApplication1/ 下的控制台程序。换句话说,你的开发机应当是装了 Visual Studio 的 Windows 环境。
资源包里都包含哪些内容
下载后解压 SOEM-EtherCAT-cia402-motorControl.zip,顶层会得到三部分。建议先重点看前两项,第三项 SOEM 是依赖,一般不用改。
| 目录 / 文件 | 作用 | 你需要做什么 |
|---|---|---|
JMCControl.sln |
Visual Studio 解决方案,包含主项目 JMCControl 等 |
用 VS 打开它进行编译 |
ConsoleApplication1/ |
电机控制主体代码(主站 + CiA 402 + 控制逻辑) | 阅读与修改,配置网卡和电机参数 |
SOEM-1.3.1/ |
SOEM 主站库完整源码(soem/、oshw/、osal/)+ 预编译的 lib/win32/libsoem.lib + 文档 doc/ |
依赖库,通常无需改动 |
ConsoleApplication1/ 里几个值得认识的文件:
motor_client.h/motor_client.cpp:定义了伺服的 PDO 映射(MAXPOS_DRIVE_RxPDO_t输出、MAXPOS_DRIVE_TxPDO_t输入),并实现主站初始化main_task;Cia402.cpp/Cia402.h:CiA 402 协议层,封装使能、位置/速度控制、角度模式等函数;ethercat_master.cpp/ethercat_master.h:周期 RT 线程与 OP 状态维持;pv_main.cpp:程序入口,里面写死了要用的 wpcap 网卡;global.h:把上面几个头文件统一引入的全局头。
编译前需要准备什么
在动手之前,先把环境和依赖核对齐,能避免后面「编不过 / 找不到网卡」两类问题:
- 操作系统:Windows(代码依赖 WinPcap 与
winmm周期定时器,未适配 Linux)。 - Visual Studio:解决方案格式为
12.00、版本标注 VS 15,建议用 Visual Studio 2017 打开(更高版本一般也能打开,但 2017 最稳妥)。 - WinPcap:SOEM 在 Windows 上抓包依赖 WinPcap(
wpcap、Packet),代码里已用#pragma comment(lib, ...)链接wpcap.lib、Packet.lib,需确保开发环境中已安装并能找到这些库。 - SOEM 库:已包含在压缩包的
SOEM-1.3.1/中,且带了预编译的libsoem.lib,一般不需要单独再去装。 - 硬件:一块 EtherCAT 从站伺服驱动器(代码里针对 RDM 电机做了识别),以及一张连接 EtherCAT 总线的网卡,并以合适的权限运行。
从下载到跑通:四步走通流程
第一步:下载并解压
在仓库页面把 SOEM-EtherCAT-cia402-motorControl.zip 下载到本地,解压到一个路径里没有中文和空格的目录(例如 D:\JMCControl),Windows 下的 VC 工程对中文路径比较敏感,能省不少麻烦。
第二步:换成你自己的网卡
这是新手最容易忽略的一步。入口文件 ConsoleApplication1/pv_main.cpp 里写死了一台 wpcap 网卡:
argvv[1] = { "\\Device\\NPF_{7FBFC157-AE62-45E0-8B22-0254F2F1E85D}" };
把它替换成你实际那块连 EtherCAT 总线的网卡的 NPF_{...} 名字(在 WinPcap 设备列表或系统里查看网卡对应的 NPF 设备名)。如果这一步不改,程序会连到错误的网口,ec_init 之后大概率发现不到从站。
第三步:用 Visual Studio 打开并编译
- 双击
JMCControl.sln,用 Visual Studio 2017 打开解决方案。 - 在顶部工具栏选择配置:平台选
x64(或Win32),配置选Debug先跑通。 - 执行「生成 → 生成解决方案」。预期结果是「生成 1 成功,0 个错误」。若报链接错误,多半是
SOEM-1.3.1/lib/win32/libsoem.lib路径或 WinPcap 库没配好,先回到上一节核对依赖。
第四步:运行并观察控制台输出
运行 JMCControl 可执行文件(建议以管理员权限运行以便抓包),在控制台里依次看到这些输出,就说明主站到 CiA 402 的链路通了:
ec_init on ... succeeded.:主站已绑定到网卡;N slaves found and configured.:发现并配置了从站(N应 ≥ 1);发现RDM电机 ...:代码按 vendor/product code 识别到了目标伺服;号电机已经进入OP状态(0x08):从站进入 OPERATIONAL;- 之后进入
Run_in_angle_mode()开始角度控制。
如果你的伺服不是那台被识别的 RDM 驱动,需要在 motor_client.cpp 里调整 eep_man / eep_id 的判定条件,或按自家驱动器改 PDO 映射。
关键参数都在哪里改
跑通之后,真正决定电机行为的是下面这几个参数,位置都很集中:
- 电机识别:
ConsoleApplication1/motor_client.cpp中判定eep_man == 0xab && eep_id == 0x1030的地方,对应你的驱动器 vendor ID / product code。 - 轴数:
motor_client.h里的SLAVECOUNT,当前是1,表示单轴。 - 减速比与编码器分辨率:
Cia402.cpp顶部的gear_ratio(默认 35)、ppr(默认 10000)、direction(方向,默认 1.0),按你的传动与编码器实际值改。 - PDO 映射:
motor_client.h里的MAXPOS_DRIVE_RxPDO_t/MAXPOS_DRIVE_TxPDO_t对应 CiA 402 的0x6040(控制字)、0x6061/0x6041(状态字)、0x60FF(目标速度)、0x6064(实际位置)等对象,按驱动器手册核对偏移。 - 控制入口:
motor_client.cpp末尾调用的是Run_in_angle_mode(),Cia402.h里还提供goto_position、set_target_velocity、MoveJ等接口,可按需切换控制模式。
常见问题
No slaves found!:九成是网卡没换对,或总线上没有上电的从站。先确认pv_main.cpp里的NPF设备名和实际接线。ec_init失败 /Excecute as root:抓包需要权限,用管理员权限运行;并确认该网卡没有被其它程序占用。- 进不了 OP 状态:控制台会打印
Slave x State=0x.. StatusCode=0x.... : 原因,按ALstatuscode对照 CiA / EtherCAT 错误码,通常是 PDO 映射或对象字典与驱动器不匹配。 - 编不过、找不到库:检查
libsoem.lib、wpcap.lib、Packet.lib是否都在库搜索路径里,以及平台(x64/Win32)与库架构是否一致。
如何参与贡献与反馈
这个项目欢迎你把踩过的坑变成可复用的改进:
- 提交 Issue:遇到编不过、跑不通或看不懂的地方,到仓库提交 Issue,写清你的系统版本、网卡型号、控制台完整输出,越具体越好排查。
- 提交 Pull Request:如果你补了新的驱动器适配、优化了 CiA 402 状态机处理,或修了一个 bug,欢迎发起 Pull Request;改动尽量小而聚焦,附上改前/改后的控制台对比更容易被合入。
关于许可证
代码采用开源许可证发布,具体条款以仓库根目录下的 LICENSE 文件为准,使用前请通读一遍,确认你的使用方式(尤其是再分发、商用)是否符合其要求。
希望这份指南能帮你尽快把这台伺服转起来;跑通后有任何改进,也欢迎回到仓库贡献你的补丁。