IgH EtherCAT Master 1.5 全流程安装部署手册（Git 源码版 + 内核源码修改 + 实时内核适配）

适用场景Ubuntu 系统 5.15 PREEMPT_RT 实时内核 Intel IGB 网卡 (I210/I211) 自定义从站地址分配修改 全程严格遵循官方文档与源码逻辑每一步可追溯、无遗漏顺序不可颠倒。第一阶段前置环境准备必须先完成否则编译必失败1.1 确认当前运行内核必须在目标实时内核下操作确保内核版本与头文件完全匹配。uname -r # 预期输出5.15.0-1091-realtime1.2 安装全量编译依赖表格依赖包作用build-essentialgcc、make 等基础编译工具链autoconf / automake / libtool生成 configure 脚本的 Autotools 工具集bootstrap 必需linux-headers-$(uname -r)内核头文件编译内核.ko 模块的唯一依赖版本必须与运行内核完全一致git拉取官方源码仓库udev / kmod设备节点管理、内核模块加载工具执行安装sudo apt update sudo apt install -y build-essential autoconf automake libtool git linux-headers-$(uname -r) udev kmod1.3 记录 EtherCAT 网卡 MAC 地址后续配置必须用到该网卡会被 EtherCAT 原生驱动接管脱离系统网络栈不能再用来上网。baship link # 记录对应网卡的link/ether后的值例如 00:1e:06:12:34:56第二阶段源码获取与初始化生成 configure 脚本2.1 拉取官方 Git 源码官方仓库地址切换到稳定分支cd /opt sudo git clone https://gitlab.com/etherlab.org/ethercat.git ethercat-stable-1.5 cd ethercat-stable-1.5 sudo git checkout stable-1.52.2 执行 bootstrap 生成编译配置脚本核心说明Git 仓库仅保留源码不存放 Autotools 生成的中间文件因此没有configure脚本必须通过bootstrap生成。如果是下载的官方 tar.gz 发布包自带 configure可跳过此步。sudo ./bootstrap2.3 bootstrap 执行后产物与功能生成文件路径功能configure源码根目录编译配置总入口脚本后续./configure的执行文件Makefile.in根目录 各子目录Makefile 模板configure 会根据配置参数生成最终 Makefileaclocal.m4根目录Autoconf 宏定义文件config.h.in根目录编译开关头文件模板验证成功无报错退出根目录出现configure可执行文件。第三阶段编译配置./configure4.1 配置命令适配你的 5.15 RTIGB 网卡场景写死内核版本杜绝切换内核导致的误编译sudo ./configure \ --prefix/usr/local \ --with-linux-dir/lib/modules/5.15.0-1091-realtime/build \ --enable-rtyes \ --enable-igbyes \ --with-igb-kernel5.15 \ --enable-genericno \ --enable-8139toono \ --enable-e1000no \ --enable-e1000eno \ --enable-eoeyes \ --enable-toolyes \ --enable-userlibyes4.2 参数逐行详解参数作用备注--prefix/usr/local用户态程序、头文件、库、配置模板的安装根目录所有用户态产物都会安装到该路径下--with-linux-dirxxx指定内核头文件路径编译内核模块的核心参数必须和目标运行内核版本完全匹配--enable-rtyes开启 PREEMPT_RT 实时内核适配机械臂实时控制必开优化中断与调度延迟--enable-igbyes编译 Intel IGB 系列网卡的 EtherCAT 原生驱动I210/I211 网卡必选无中断轮询模式性能远高于通用驱动--with-igb-kernel5.15指定 IGB 驱动适配的内核版本匹配 5.15 内核避免驱动兼容性问题--enable-genericno关闭通用网卡驱动只用原生 IGB精简内核模块体积--enable-8139too/e1000/e1000eno关闭其他型号网卡驱动不需要的驱动全部关闭--enable-eoeyes开启 EoE 以太网隧道功能默认开启不需要可关闭--enable-toolyes编译 ethercat 命令行工具必开调试、配置总线都要使用--enable-userlibyes编译用户态 libethercat 库必开应用层调用 EtherCAT 必须链接该库4.3 配置成功后产物生成文件路径功能Makefile根目录 各子目录最终编译脚本make命令的执行入口config.h根目录编译开关头文件控制哪些功能编译进源码config.status根目录配置状态文件记录本次 configure 的所有参数config.log根目录配置日志编译失败时排查问题用验证成功末尾输出Configuration complete且 IGB 驱动状态显示为yes。第四阶段编译执行5.1 全量编译首次编译必做sudo make -j$(nproc)-j$(nproc)调用所有 CPU 核心加速编译。编译后核心产物路径与功能一、内核态驱动.ko 文件核心产物文件源码内路径功能ec_master.kokernel/ec_master.koEtherCAT 主站核心内核模块实现主站状态机、过程数据、邮箱协议、DC 同步等全部核心逻辑ec_igb.kodevices/igb/ec_igb.koIntel IGB 网卡的 EtherCAT 原生驱动绕过系统网络栈采用无中断轮询模式保障实时性二、用户态工具产物文件源码内路径功能ethercattool/ethercat命令行调试工具查看从站、读写 SDO、配置总线、调试寄存器三、用户态开发库产物文件源码内路径功能libethercat.alib/.libs/libethercat.a静态库应用层静态链接使用libethercat.solib/.libs/libethercat.so动态库应用层动态链接使用ecrt.hinclude/ecrt.h应用层 API 头文件所有 EtherCAT 应用开发必须包含5.2 仅重编内核模块修改内核源码后推荐如果只修改了master/fsm_master.c这类内核代码无需全量重编cd kernel sudo make clean sudo make cd ..5.3 清理编译产物普通清理保留 configure 配置sudo make clean删除所有.o、.ko 编译中间文件彻底清理回到源码初始状态sudo make distclean删除所有编译产物、Makefile、config.h红线修改 configure 参数、大幅修改源码后必须执行make distclean重新走 configure→make 流程。第五阶段系统安装必须 root 权限分两步安装用户态文件 内核模块6.1 安装用户态文件sudo make install安装后各文件路径与功能安装路径内容功能/usr/local/bin/ethercat全局可执行的命令行调试工具/usr/local/include/ecrt.h、ecrt_*.h应用开发头文件/usr/local/lib/libethercat.a / libethercat.so用户态库文件应用程序链接使用/usr/local/etc/ethercat.conf配置模板systemd 模式主配置文件模板/usr/local/etc/sysconfig/ethercat配置模板SysV init 模式配置文件模板/usr/local/etc/init.d/ethercat启动脚本SysV init 启动脚本/usr/local/sbin/ethercatctl控制命令systemd 模式下启停主站的命令/usr/local/share/man/帮助文档man 手册【体系一systemd】 【体系二SysV init】/usr/local/sbin/ethercatctl /usr/local/etc/init.d/ethercat│ 启停脚本(用 systemd 时) │ 启停脚本(软链→/etc/init.d/ethercat)│ 读取 ⬇ │ 读取 ⬇│ │/usr/local/etc/ethercat.conf /etc/sysconfig/ethercat│ ││ │└───────── modprobe ec_master ────────┘main_devicesMAC殊途同归最终都加载同一个内核模块6.2 安装内核模块到系统sudo make modules_install安装后路径/lib/modules/5.15.0-1091-realtime/ethercat/Ubuntu 中/lib与/usr/lib为软链接等价 目录下文件ec_master.ko主站核心模块ec_igb.koIGB 网卡驱动模块作用把编译好的内核驱动放到系统内核模块目录系统才能通过modprobe加载。6.3 更新内核模块依赖数据库必做sudo depmod -a作用扫描所有内核模块更新/lib/modules/5.15.0-1091-realtime/modules.dep依赖表让modprobe命令能找到ec_master和ec_igb模块自动处理依赖关系。红线这步必做否则 modprobe 会报错Module ec_master not found。第六阶段系统配置所有 /etc 下配置都不会自动生成必须手动部署7.1 主配置文件部署systemd 模式Ubuntu 适用复制模板到系统配置目录sudo cp /usr/local/etc/ethercat.conf /etc/ethercat.conf编辑核心配置sudo vim /etc/ethercat.conf修改两个必填参数# 填写你的EtherCAT网卡MAC地址小写、冒号分隔 MASTER0_DEVICE00:1e:06:xx:xx:xx # 指定使用的网卡驱动IGB网卡填igb DEVICE_MODULESigb补充说明多主站多张网卡新增MASTER1_DEVICE、MASTER2_DEVICE...填ff:ff:ff:ff:ff:ff表示自动匹配第一个可用网卡仅调试用DEVICE_MODULES可填多个驱动空格分隔7.2 SysV 兼容配置可选兼容旧版 init.d 脚本systemd 系统建议保留避免报错sudo mkdir -p /etc/sysconfig sudo cp /usr/local/etc/sysconfig/ethercat /etc/sysconfig/ethercat7.3 Udev 设备权限规则配置为什么要做主站加载后会创建/dev/EtherCAT0字符设备默认权限root:root 0660普通用户无法执行 ethercat 命令每次都要 sudo。操作步骤创建规则文件sudo tee /etc/udev/rules.d/99-EtherCAT.rules EOF KERNELEtherCAT[0-9]*, MODE0664, GROUProot EOF重载 udev 规则使其生效sudo udevadm control --reload-rules sudo udevadm trigger7.4 动态库路径配置可选解决应用程序找不到libethercat.so的问题sudo echo /usr/local/lib /etc/ld.so.conf.d/ethercat.conf sudo ldconfig7.5 开机自启配置生产环境推荐sudo systemctl enable ethercat第七阶段启动主站与功能验证8.1 启动主站服务sudo ethercatctl start8.2 验证内核模块加载lsmod | grep ec_正常输出ec_igb xxx 0 ec_master xxx 1 ec_igb8.3 查看内核启动日志dmesg | grep -i ethercat正常日志顺序EtherCAT: Master driver 1.5.xEtherCAT: 1 master waiting for devices.ec_igb: Intel(R) PRO/1000 Network Driver ...EtherCAT: Accepting device xx:xx:xx:xx:xx:xx for master 0EtherCAT: Link state changed to UP.EtherCAT: X slave(s) responding.EtherCAT: Scanning bus.EtherCAT: Bus scanning completed in X ms.8.4 验证从站与地址分配验证你的源码修改ethercat slaves输出第一列 Station Address应显示你配置的 1002、1003... 固定地址证明 fsm_master.c 修改生效。8.5 常用验证命令# 查看主站状态 ethercat master # 查看PDO映射 ethercat pdos # 查看从站详细信息 ethercat slaves -v第八阶段修改源码后的标准更新流程高频使用修改fsm_master.c等内核源码后按以下步骤更新确保修改生效# 1. 进入源码目录 cd /opt/ethercat-stable-1.5 # 2. 停止主站服务 sudo ethercatctl stop # 3. 清理内核模块编译产物 cd kernel sudo make clean cd .. # 4. 重新编译内核模块 sudo make -j$(nproc) # 5. 重新安装内核模块 sudo make modules_install # 6. 更新模块依赖 sudo depmod -a # 7. 重启主站服务 sudo ethercatctl start # 8. 验证修改效果 ethercat slaves第九阶段全量文件路径与功能汇总一、源码编译阶段类别路径说明主站状态机源码master/fsm_master.c从站地址分配逻辑所在文件主站核心模块kernel/ec_master.ko编译好的主站内核模块网卡驱动模块devices/igb/ec_igb.ko编译好的 IGB 原生驱动命令行工具tool/ethercat编译好的调试工具二、系统安装后类别路径说明内核模块目录/lib/modules/5.15.0-1091-realtime/ethercat/系统内核模块存放位置主配置文件/etc/ethercat.confsystemd 读取的主配置兼容配置/etc/sysconfig/ethercatSysV 脚本读取的配置udev 规则/etc/udev/rules.d/99-EtherCAT.rules设备节点权限规则命令行工具/usr/local/bin/ethercat全局可用的调试命令头文件/usr/local/include/ecrt.h应用开发头文件库文件/usr/local/lib/libethercat.*应用链接库控制命令/usr/local/sbin/ethercatctl主站启停命令绝对不能踩的红线内核版本严格匹配编译用的 headers、运行的内核、安装的模块目录三者版本必须完全一致差一个小版本都加载失败。修改源码必清理改完.c 文件必须make clean再编译否则旧缓存导致修改不生效。/etc 下配置不会自动生成所有系统级配置都要手动从/usr/local/etc复制是 90% 新手启动失败的原因。depmod 必做安装完内核模块必须执行depmod -a否则 modprobe 找不到模块。IGB 网卡脱离系统网络栈用作 EtherCAT 的网卡系统里看不到 IP、不能上网属于正常现象原生驱动就是绕过网络栈直接操作硬件。实时内核下才能保障控制性能generic 内核也能运行但实时性差机械臂控制会出现抖动。