【离线版下载】SOEM + CiA 402 电机控制代码包:一套能直接编译运行的 EtherCAT 伺服驱动方案

原创2026-11-01 17:17:191,424 阅读

【离线版下载】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:把上面几个头文件统一引入的全局头。

编译前需要准备什么

在动手之前,先把环境和依赖核对齐,能避免后面「编不过 / 找不到网卡」两类问题:

  1. 操作系统:Windows(代码依赖 WinPcap 与 winmm 周期定时器,未适配 Linux)。
  2. Visual Studio:解决方案格式为 12.00、版本标注 VS 15,建议用 Visual Studio 2017 打开(更高版本一般也能打开,但 2017 最稳妥)。
  3. WinPcap:SOEM 在 Windows 上抓包依赖 WinPcap(wpcap、Packet),代码里已用 #pragma comment(lib, ...) 链接 wpcap.lib、Packet.lib,需确保开发环境中已安装并能找到这些库。
  4. SOEM 库:已包含在压缩包的 SOEM-1.3.1/ 中,且带了预编译的 libsoem.lib,一般不需要单独再去装。
  5. 硬件:一块 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 打开并编译

  1. 双击 JMCControl.sln,用 Visual Studio 2017 打开解决方案。
  2. 在顶部工具栏选择配置:平台选 x64(或 Win32),配置选 Debug 先跑通。
  3. 执行「生成 → 生成解决方案」。预期结果是「生成 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 文件为准,使用前请通读一遍,确认你的使用方式(尤其是再分发、商用)是否符合其要求。

希望这份指南能帮你尽快把这台伺服转起来;跑通后有任何改进,也欢迎回到仓库贡献你的补丁。

登录后查看全文
SOEM-EtherCAT-cia402电机控制代码