LubanCat RK3588 实时 Linux 开发实战（十四）：EtherCAT 主站方案选择与 Full SDK 准备

企鹅的蚂蚁2026-09-17 9:34

摘要：手册中的 EtherCAT 示例不能直接套用到所有 LubanCat 系统。本文从内核版本、板级设备树、主机/目标机职责和 Full SDK 目录四个方面，建立可回滚的移植起点。

适用对象：已经能启动 LubanCat-5IOB，准备在 Linux 6.1 PREEMPT_RT 上集成 IgH EtherCAT Master 的开发者。本文只准备源码和环境，不向目标板写入文件。

文章目录

    • 本文要解决什么问题
    • 一、先确认这不是"安装一个用户态库"
      • [1.1 EtherCAT 主站不是单一组件](#1.1 EtherCAT 主站不是单一组件)
      • [1.2 为什么旧模块不能直接复制](#1.2 为什么旧模块不能直接复制)
    • 二、区分主机、目标板和串口
      • [2.1 三种环境的职责必须明确](#2.1 三种环境的职责必须明确)
    • [三、为什么需要 Full SDK](#三、为什么需要 Full SDK)
      • [3.1 先确认缺的是工程，而不是命令](#3.1 先确认缺的是工程，而不是命令)
      • [3.2 安全提取 Full SDK 中的 EtherCAT 工程](#3.2 安全提取 Full SDK 中的 EtherCAT 工程)
    • [四、应用补丁前检查 Git 状态](#四、应用补丁前检查 Git 状态)
      • [4.1 先保留工作树状态](#4.1 先保留工作树状态)
    • 五、建立版本基线
      • [5.1 开发主机基线](#5.1 开发主机基线)
      • [5.2 目标板基线](#5.2 目标板基线)
    • 六、小结
    • 七、常见误区
      • [7.1 把 EtherCAT 当成普通用户态库](#7.1 把 EtherCAT 当成普通用户态库)
      • [7.2 直接把 Full SDK 整体覆盖到现有 SDK](#7.2 直接把 Full SDK 整体覆盖到现有 SDK)
      • [7.3 只记录内核大版本](#7.3 只记录内核大版本)
      • [7.4 直接追上游最新版](#7.4 直接追上游最新版)
    • 八、本文验收清单
    • 工作流实测截图
    • 九、系列导航

本文要解决什么问题

很多 EtherCAT 移植失败，并不是出在"不会编译"，而是从一开始就把 用户态工具、主站内核模块、网卡驱动、设备树和 PREEMPT_RT 内核 混在了一起。尤其在 LubanCat/RK3588 上，如果直接照搬旧教程或只复制一个 .ko，很容易遇到 vermagic 不匹配、网卡绑定错误、设备树节点不匹配等问题。

本文先不急着编译，而是建立一个可追溯、可回滚的 EtherCAT 移植基线。完成本文后，应能明确回答下面 5 个问题：

检查项 本文要得到的结论
EtherCAT 主站由哪些层组成？ 内核实时能力 + 主站模块/网卡适配 + 用户态工具
为什么不能直接复制旧 .ko？ 内核版本、配置、符号和设备树必须匹配
为什么需要 Full SDK？ 精简 SDK 可能缺少 external/ethercat_igh
Full SDK 应如何合并？ 只提取需要的 EtherCAT 外部工程，不覆盖整个工作 SDK
编译前必须记录什么？ manifest、内核 Git 版本、目标板系统和启动参数

本文实测环境 ：LubanCat-5IOB / RK3588 / Ubuntu 22.04.5 LTS / Linux 6.1.99-rt36-rk3588-ethercat。其他板卡、SDK 或内核版本请以现场输出为准，不能直接照抄本文的 DTB、MAC 地址或模块文件。

一、先确认这不是"安装一个用户态库"

1.1 EtherCAT 主站不是单一组件

EtherCAT 主站由三部分组成：

  1. 内核实时能力（PREEMPT_RT、调度和 CPU 隔离）；
  2. EtherCAT 主站内核模块（ec_master.ko 和硬件适配模块）；
  3. 用户态工具和库（ethercat、libethercat.so、配置文件）。

1.2 为什么旧模块不能直接复制

因此，目标板当前的内核、设备树和网口控制器必须与模块一起验证。直接把另一台板卡编译出的 .ko 复制过来，通常会遇到 vermagic 不匹配、设备树没有匹配到驱动，或主站绑定了错误网口。

二、区分主机、目标板和串口

2.1 三种环境的职责必须明确

环境 主要职责 典型命令
开发主机 解压 Full SDK、打补丁、编译内核和模块 ./build.sh、make、sha256sum
目标板 安装 DEB、加载模块、连接从站、运行测试 dpkg、modprobe、ethercat
串口终端 网络中断或启动失败时的恢复通道 picocom、U-Boot/initramfs 命令

本次设备是 LubanCat-5IOB/RK3588，目标系统为 Ubuntu 22.04.5 LTS，运行内核最终为 6.1.99-rt36-rk3588-ethercat。手册第 53 章的示例路径和旧内核版本只作为方法参考，不能代替现场版本检查。

三、为什么需要 Full SDK

3.1 先确认缺的是工程，而不是命令

精简 SDK 可能包含 kernel-6.1，但不一定包含 external/ethercat_igh。本次首次执行：

bash 复制代码 
git am ../external/ethercat_igh/0001-add-support-ethercat-for-lubancat.patch

得到"没有那个文件或目录"，原因不是 Git 语法，而是当前 SDK 中没有 EtherCAT 外部工程。Full SDK 压缩包位于：

text 复制代码 
/home/zhaoyj/lubancat/LubanCat_Full/
└── LubanCat_Linux_Generic_Full_SDK_20260424.tgz

3.2 安全提取 Full SDK 中的 EtherCAT 工程

先定义工作 SDK 并检查压缩包顶层目录，不要直接解压到工作树根目录：

bash 复制代码 
SDK=/home/zhaoyj/lubancat/LubanCat_SDK
FULL=/home/zhaoyj/lubancat/LubanCat_Full/LubanCat_Linux_Generic_Full_SDK_20260424.tgz
tar -tzf "$FULL" | sed -n '1,30p'

合并前先检查目标是否已存在：

bash 复制代码 
test ! -e "$SDK/external/ethercat_igh" || {
    echo '目标目录已经存在，请先检查版本'
    exit 1
}

确认顶层结构后解压到临时目录，只合并其中的 external/ethercat_igh，不要把两个 SDK 的全部文件互相覆盖：

bash 复制代码 
tmp=$(mktemp -d)
tar -xzf "$FULL" -C "$tmp"
src=$(find "$tmp" -type d -path '*/external/ethercat_igh' -print -quit)
test -n "$src" || { echo 'Full SDK 中未找到 external/ethercat_igh'; exit 1; }
mkdir -p "$SDK/external"
cp -a "$src" "$SDK/external/ethercat_igh"
rm -rf "$tmp"

不要把两个不同 manifest 的整个 SDK 互相覆盖；内核、设备树和构建脚本必须来自同一个 SDK 版本。本次使用的 manifest 是 lubancat_linux_generic_20260424.xml。

四、应用补丁前检查 Git 状态

4.1 先保留工作树状态

bash 复制代码 
cd "$SDK/kernel-6.1"
git status --short --branch
ls -l ../external/ethercat_igh/0001-add-support-ethercat-for-lubancat.patch
git am ../external/ethercat_igh/0001-add-support-ethercat-for-lubancat.patch
git log --oneline -3

如果 git am 中途失败，先保存冲突状态和日志，不要使用 git reset --hard 覆盖已有修改。### 4.2 检查 EtherCAT 专用 GMAC 的设备树匹配

补丁应用后应检查设备树是否把 RK3588 EtherCAT GMAC 标记为：

dts 复制代码 
compatible = "rockchip,rk3588-gmac-ethercat", "snps,dwmac-4.20a";

这一步让 EtherCAT 专用 STMMAC 驱动能够匹配 fe1c0000 控制器；普通 GMAC 网口不能代替它。

五、建立版本基线

5.1 开发主机基线

在编译前保存：

bash 复制代码 
cd "$SDK"
git -C kernel-6.1 rev-parse --short HEAD
grep -E 'Manifest|RK_KERNEL_VERSION|RK_KERNEL_DTS' output/.config 2>/dev/null || true

5.2 目标板基线

目标板则保存：

bash 复制代码 
uname -a
cat /etc/os-release
cat /proc/cmdline
findmnt /
ip -br link

主机的 defconfig 名称不能推导目标发行版，目标板的 /etc/os-release 才是系统版本证据。

六、小结

本阶段的交付物不是一个"看起来像 EtherCAT 的目录"，而是一套明确的版本关系：

  • Full SDK 和 kernel-6.1 来自同一 manifest；
  • EtherCAT 补丁应用在正确的内核树；
  • 主站 GMAC 节点与板卡端口对应；
  • 主机负责构建，目标板只在备份后安装；
  • 串口始终保留为回滚通道。

下一篇将使用这套基线编译 IGH 用户态工具、主站模块和 RK3588 STMMAC 适配模块。

七、常见误区

7.1 把 EtherCAT 当成普通用户态库

只安装 libethercat.so 和 ethercat 命令，并不会让 RK3588 的 GMAC 自动变成 EtherCAT 主站。主站仍依赖 ec_master.ko、硬件适配模块以及正确的设备树匹配。

7.2 直接把 Full SDK 整体覆盖到现有 SDK

这是最危险的做法之一。两个 SDK 若 manifest 不一致，可能同时替换内核、设备树、构建脚本和外部组件，后续即使"编译成功"，也很难再判断产物究竟来自哪一套源码。

7.3 只记录内核大版本

6.1 远远不够。后续模块验收至少需要完整 kernelrelease、.config、Module.symvers 和交叉编译器保持一致。

7.4 直接追上游最新版

截至本文整理时，EtherLab 上游已经把 stable-1.6 作为新生产系统的推荐分支；但 LubanCat Full SDK 内的 EtherCAT 补丁和 STMMAC 适配是围绕厂商集成版本准备的。本系列优先保证 SDK/补丁/内核的一致性，不建议在没有重新适配和回归测试的情况下直接替换上游分支。

八、本文验收清单

  • 已确认目标板型号和当前运行内核；
  • 已确认 /etc/os-release，没有用 defconfig 名称猜发行版；
  • Full SDK 中确实存在 external/ethercat_igh；
  • 没有将两个不同 manifest 的 SDK 整体互相覆盖；
  • EtherCAT 补丁已成功应用到正确的 kernel-6.1；
  • 已检查 EtherCAT 专用 GMAC 的 compatible；
  • 已保存内核 Git 提交、manifest 和目标板基线；
  • 串口和旧内核/恢复介质仍然可用。

发布时建议配图 ：① Full SDK 与精简 SDK 目录对比；② git am 成功后的终端输出；③ EtherCAT GMAC 设备树节点。CSDN V5.0 会把图片作为正向质量元素，优先使用真实终端或硬件截图，不要使用与正文无关的装饰图。

工作流实测截图

图1：Full SDK 中的 ethercat_igh、master 和 stmmac 目录；文件来自本地 20260424 Full SDK 压缩包。

图2：Git 提交记录和 rk3588-gmac-ethercat compatible 字符串，确认补丁与芯片族匹配。

图3：最终 DTS 的 isolcpus、nohz_full 和 rcu_nocbs 参数；提交分支工作树保持 clean。

九、系列导航

上一篇：LubanCat RK3588 实时 Linux 开发实战（十三）：RT-Linux 压力测试与耐久验证

下一篇：LubanCat RK3588 实时 Linux 开发实战（十五）：编译 IgH EtherCAT 主站与 RK3588 STMMAC 驱动

标签 ：EtherCAT LubanCat RK3588 Full SDK 嵌入式Linux

参考资料：EtherLab EtherCAT Master 官方主页、stable-1.5 README 和野火 LubanCat 快速使用手册第 53 章（PDF 第 697 页）。

相关推荐
企鹅的蚂蚁19 小时前
LubanCat RK3588 实时 Linux 开发（七）：YT6801 PCIe 网卡驱动移植与 vermagic 排查
linux·rk3588·linux驱动·yt6801·pcie网卡·vermagic
程序猿编码1 天前
扔掉 Python！纯 C++ 本地跑扩散 TTS，GGML 加持，支持 RK3588 NPU 加速
c++·计算机视觉·大模型·transformer·rk3588·推理·ggml
企鹅的蚂蚁2 天前
LubanCat RK3588 实时 Linux 开发（九）：从 U-Boot 到 initramfs 的串口启动故障分析
linux·rk3588·u-boot·串口调试·initramfs·linux启动
@嵌入式扫地僧5 天前
国产 RISC-V 机器人关节 MCU 量产落地解析：硬件 EtherCAT 支持与进口替代完整指南
机器人·risc-v·ethercat·国产化替代·机器人关节mcu
北京盟通科技官方账号6 天前
高通 IQ-9075 部署 EC-Master 实战指南：环境构建与实时 Linux (RT) 系统烧录
人工智能·机器人·yocto·ethercat·ecmaster·盟通科技·rt kernel
企鹅的蚂蚁6 天前
LubanCat RK3588 实时 Linux 开发（六）：启用 gs_usb 驱动并完成 USB-CAN 收发
linux·rk3588·linux驱动·socketcan·gs_usb·usb-can
柔情的菜刀8 天前
RK3588 DDR初始化bin修改
rk3588
企鹅的蚂蚁8 天前
LubanCat RK3588 实时内核移植第一步：先确认硬件与系统版本
linux·lubancat·嵌入式linux·freempt_rt
零意@12 天前
RK3588 debian11的SDK代码新增一个分区怎么修改
rk3588·新增分区·分区大小·分区文件
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02数学公理体系大全:第六章 选择公理的等价形式及证明03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07人工智能（AI）发展史：详细里程碑082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09ZCode 周末送额度活动开启：3 亿 Token 免费领取10【一等奖版】2026 国赛 A题 药材的烘干问题