尧图网站建设 免费方案咨询
ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

首页/资讯中心/资讯详情

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

发布时间：2026/8/7 10:12:10 尧图网站建设
IgH EtherCAT Master 1.5 全流程安装部署手册（Git 源码版 + 内核源码修改 + 实时内核适配）

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

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

1.1 确认当前运行内核

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

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

1.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 kmod

1.3 记录 EtherCAT 网卡 MAC 地址

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

bash

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

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

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

sudo ./bootstrap

2.3 bootstrap 执行后产物与功能

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

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

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

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

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

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 全量编译（首次编译必做）

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_devices="MAC"
（殊途同归：最终都加载同一个内核模块）

6.2 安装内核模块到系统

sudo make modules_install
安装后路径
/lib/modules/5.15.0-1091-realtime/ethercat/

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

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

作用：把编译好的内核驱动放到系统内核模块目录，系统才能通过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 适用）

  1. 复制模板到系统配置目录
sudo cp /usr/local/etc/ethercat.conf /etc/ethercat.conf
  1. 编辑核心配置
sudo vim /etc/ethercat.conf
  1. 修改两个必填参数
# 填写你的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 系统建议保留避免报错：

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. 创建规则文件
sudo tee /etc/udev/rules.d/99-EtherCAT.rules << 'EOF' KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="root" EOF
  1. 重载 udev 规则使其生效
sudo udevadm control --reload-rules sudo udevadm trigger

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

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

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

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

sudo systemctl enable ethercat

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

8.1 启动主站服务

sudo ethercatctl start

8.2 验证内核模块加载

lsmod | grep ec_

正常输出：

ec_igb xxx 0 ec_master xxx 1 ec_igb

8.3 查看内核启动日志

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 验证从站与地址分配（验证你的源码修改）

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主站启停命令

绝对不能踩的红线

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