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

适用场景：Ubuntu 系统 + 5.15 PREEMPT_RT 实时内核 + Intel IGB 网卡 (I210/I211) + 自定义从站地址分配修改 全程严格遵循官方文档与源码逻辑，每一步可追溯、无遗漏，顺序不可颠倒。

---

第一阶段：前置环境准备（必须先完成，否则编译必失败）

1.1 确认当前运行内核

必须在目标实时内核下操作，确保内核版本与头文件完全匹配。

bash

uname -r
# 预期输出：5.15.0-1091-realtime

1.2 安装全量编译依赖

表格

依赖包	作用
build-essential	gcc、make 等基础编译工具链
autoconf / automake / libtool	生成 configure 脚本的 Autotools 工具集（bootstrap 必需）
linux-headers-$(uname -r)	内核头文件，编译内核.ko 模块的唯一依赖，版本必须与运行内核完全一致
git	拉取官方源码仓库
udev / kmod	设备节点管理、内核模块加载工具

执行安装：

bash

sudo apt update
sudo apt install -y build-essential autoconf automake libtool git linux-headers-$(uname -r) udev kmod

1.3 记录 EtherCAT 网卡 MAC 地址

后续配置必须用到，该网卡会被 EtherCAT 原生驱动接管，脱离系统网络栈（不能再用来上网）。

bash

ip link
# 记录对应网卡的link/ether后的值，例如 00:1e:06:12:34:56

---

第二阶段：源码获取与初始化（生成 configure 脚本）

2.1 拉取官方 Git 源码

官方仓库地址，切换到稳定分支：

bash

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.5

2.2 执行 bootstrap 生成编译配置脚本

核心说明 ：Git 仓库仅保留源码，不存放 Autotools 生成的中间文件，因此没有configure脚本，必须通过bootstrap生成。如果是下载的官方 tar.gz 发布包，自带 configure，可跳过此步。

bash

sudo ./bootstrap

2.3 bootstrap 执行后产物与功能

表格

生成文件	路径	功能
configure	源码根目录	编译配置总入口脚本，后续./configure的执行文件
Makefile.in	根目录 + 各子目录	Makefile 模板，configure 会根据配置参数生成最终 Makefile
aclocal.m4	根目录	Autoconf 宏定义文件
config.h.in	根目录	编译开关头文件模板

验证成功：无报错退出，根目录出现configure可执行文件。

---

第三阶段：自定义内核源码修改（固定从站地址分配）

3.1 目标文件定位

文件路径 ：master/fsm_master.c 对应功能：主站状态机核心文件，总线扫描完成后初始化从站、分配 Station Address（站点地址）。

3.2 修改位置

找到ec_fsm_master_state_broadcast函数内的「init slaves」循环段，也就是你之前调整从站地址的代码块。

3.3 标准修改步骤

1. 备份原文件（出错可回滚）

bash

sudo cp master/fsm_master.c master/fsm_master.c.bak

1. 编辑源码，替换地址分配逻辑

bash

sudo vim master/fsm_master.c

将默认的i + 1002替换为你的多机械臂分段地址逻辑，保证：

• 地址为 16 位无符号整数，范围 1~65535，不可为 0
• 同一条物理总线内地址无重复，避免寻址冲突
• 不改动ring_position、dev_idx的计算逻辑

3.4 重要提醒

修改源码后，必须清理旧编译产物再重新编译，否则目标文件缓存会导致修改不生效。

---

第四阶段：编译配置（./configure）

4.1 配置命令（适配你的 5.15 RT+IGB 网卡场景）

写死内核版本，杜绝切换内核导致的误编译：

bash

sudo ./configure \
    --prefix=/usr/local \
    --with-linux-dir=/lib/modules/5.15.0-1091-realtime/build \
    --enable-rt=yes \
    --enable-igb=yes \
    --with-igb-kernel=5.15 \
    --enable-generic=no \
    --enable-8139too=no \
    --enable-e1000=no \
    --enable-e1000e=no \
    --enable-eoe=yes \
    --enable-tool=yes \
    --enable-userlib=yes

4.2 参数逐行详解

表格

参数	作用	备注
--prefix=/usr/local	用户态程序、头文件、库、配置模板的安装根目录	所有用户态产物都会安装到该路径下
--with-linux-dir=xxx	指定内核头文件路径，编译内核模块的核心参数	必须和目标运行内核版本完全匹配
--enable-rt=yes	开启 PREEMPT_RT 实时内核适配	机械臂实时控制必开，优化中断与调度延迟
--enable-igb=yes	编译 Intel IGB 系列网卡的 EtherCAT 原生驱动	I210/I211 网卡必选，无中断轮询模式，性能远高于通用驱动
--with-igb-kernel=5.15	指定 IGB 驱动适配的内核版本	匹配 5.15 内核，避免驱动兼容性问题
--enable-generic=no	关闭通用网卡驱动	只用原生 IGB，精简内核模块体积
--enable-8139too/e1000/e1000e=no	关闭其他型号网卡驱动	不需要的驱动全部关闭
--enable-eoe=yes	开启 EoE 以太网隧道功能	默认开启，不需要可关闭
--enable-tool=yes	编译 ethercat 命令行工具	必开，调试、配置总线都要使用
--enable-userlib=yes	编译用户态 libethercat 库	必开，应用层调用 EtherCAT 必须链接该库

4.3 配置成功后产物

表格

生成文件	路径	功能
Makefile	根目录 + 各子目录	最终编译脚本，make命令的执行入口
config.h	根目录	编译开关头文件，控制哪些功能编译进源码
config.status	根目录	配置状态文件，记录本次 configure 的所有参数
config.log	根目录	配置日志，编译失败时排查问题用

验证成功：末尾输出Configuration complete，且 IGB 驱动状态显示为yes。

---

第五阶段：编译执行

5.1 全量编译（首次编译必做）

bash

sudo make -j$(nproc)

-j$(nproc) 调用所有 CPU 核心加速编译。

编译后核心产物路径与功能

一、内核态驱动（.ko 文件，核心）

表格

产物文件	源码内路径	功能
ec_master.ko	kernel/ec_master.ko	EtherCAT 主站核心内核模块，实现主站状态机、过程数据、邮箱协议、DC 同步等全部核心逻辑
ec_igb.ko	devices/igb/ec_igb.ko	Intel IGB 网卡的 EtherCAT 原生驱动，绕过系统网络栈，采用无中断轮询模式，保障实时性

二、用户态工具

表格

产物文件	源码内路径	功能
ethercat	tool/ethercat	命令行调试工具，查看从站、读写 SDO、配置总线、调试寄存器

三、用户态开发库

表格

产物文件	源码内路径	功能
libethercat.a	lib/.libs/libethercat.a	静态库，应用层静态链接使用
libethercat.so	lib/.libs/libethercat.so	动态库，应用层动态链接使用
ecrt.h	include/ecrt.h	应用层 API 头文件，所有 EtherCAT 应用开发必须包含

5.2 仅重编内核模块（修改内核源码后推荐）

如果只修改了master/fsm_master.c这类内核代码，无需全量重编：

bash

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 安装用户态文件

bash

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 手册

6.2 安装内核模块到系统

bash

sudo make modules_install

安装后路径

plaintext

/lib/modules/5.15.0-1091-realtime/ethercat/

（Ubuntu 中/lib与/usr/lib为软链接，等价） 目录下文件：

• ec_master.ko：主站核心模块
• ec_igb.ko：IGB 网卡驱动模块

作用：把编译好的内核驱动放到系统内核模块目录，系统才能通过modprobe加载。

6.3 更新内核模块依赖数据库（必做）

bash

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 适用）

1. 复制模板到系统配置目录

bash

sudo cp /usr/local/etc/ethercat.conf /etc/ethercat.conf

1. 编辑核心配置

bash

sudo vim /etc/ethercat.conf

1. 修改两个必填参数

ini

# 填写你的EtherCAT网卡MAC地址，小写、冒号分隔
MASTER0_DEVICE="00:1e:06:xx:xx:xx"

# 指定使用的网卡驱动，IGB网卡填igb
DEVICE_MODULES="igb"

补充说明：

• 多主站（多张网卡）：新增MASTER1_DEVICE、MASTER2_DEVICE...
• 填ff:ff:ff:ff:ff:ff表示自动匹配第一个可用网卡，仅调试用
• DEVICE_MODULES可填多个驱动，空格分隔

7.2 SysV 兼容配置（可选）

兼容旧版 init.d 脚本，systemd 系统建议保留避免报错：

bash

sudo mkdir -p /etc/sysconfig
sudo cp /usr/local/etc/sysconfig/ethercat /etc/sysconfig/ethercat

7.3 Udev 设备权限规则配置

为什么要做

主站加载后会创建/dev/EtherCAT0字符设备，默认权限root:root 0660，普通用户无法执行 ethercat 命令，每次都要 sudo。

操作步骤

1. 创建规则文件

bash

sudo tee /etc/udev/rules.d/99-EtherCAT.rules << 'EOF'
KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="root"
EOF

1. 重载 udev 规则使其生效

bash

sudo udevadm control --reload-rules
sudo udevadm trigger

7.4 动态库路径配置（可选）

解决应用程序找不到libethercat.so的问题：

bash

sudo echo "/usr/local/lib" >> /etc/ld.so.conf.d/ethercat.conf
sudo ldconfig

7.5 开机自启配置（生产环境推荐）

bash

sudo systemctl enable ethercat

---

第八阶段：启动主站与功能验证

8.1 启动主站服务

bash

sudo ethercatctl start

8.2 验证内核模块加载

bash

lsmod | grep ec_

正常输出：

plaintext

ec_igb                xxx  0
ec_master             xxx  1 ec_igb

8.3 查看内核启动日志

bash

dmesg | grep -i ethercat

正常日志顺序：

1. EtherCAT: Master driver 1.5.x
2. EtherCAT: 1 master waiting for devices.
3. ec_igb: Intel(R) PRO/1000 Network Driver ...
4. EtherCAT: Accepting device xx:xx:xx:xx:xx:xx for master 0
5. EtherCAT: Link state changed to UP.
6. EtherCAT: X slave(s) responding.
7. EtherCAT: Scanning bus.
8. EtherCAT: Bus scanning completed in X ms.

8.4 验证从站与地址分配（验证你的源码修改）

bash

ethercat slaves

输出第一列 Station Address，应显示你配置的 1002、1003... 固定地址，证明 fsm_master.c 修改生效。

8.5 常用验证命令

bash

# 查看主站状态
ethercat master

# 查看PDO映射
ethercat pdos

# 查看从站详细信息
ethercat slaves -v

---

第九阶段：修改源码后的标准更新流程（高频使用）

修改fsm_master.c等内核源码后，按以下步骤更新，确保修改生效：

bash

# 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.conf	systemd 读取的主配置
兼容配置	/etc/sysconfig/ethercat	SysV 脚本读取的配置
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	主站启停命令

---

绝对不能踩的红线

1. 内核版本严格匹配：编译用的 headers、运行的内核、安装的模块目录三者版本必须完全一致，差一个小版本都加载失败。
2. 修改源码必清理 ：改完.c 文件必须make clean再编译，否则旧缓存导致修改不生效。
3. /etc 下配置不会自动生成 ：所有系统级配置都要手动从/usr/local/etc复制，是 90% 新手启动失败的原因。
4. depmod 必做 ：安装完内核模块必须执行depmod -a，否则 modprobe 找不到模块。
5. IGB 网卡脱离系统网络栈：用作 EtherCAT 的网卡，系统里看不到 IP、不能上网，属于正常现象，原生驱动就是绕过网络栈直接操作硬件。
6. 实时内核下才能保障控制性能：generic 内核也能运行，但实时性差，机械臂控制会出现抖动。