【原创】IgH EtherCAT主站详解(十七)--命令行管理工具解析及使用说明

目录

ethercat 命令行工具

第六章 — 工具编译、安装与全部 33 个子命令详解

概览

ethercat 工具是什么?

ethercat 是 IgH EtherCAT Master 提供的命令行管理工具，用于在用户空间与 EtherCAT 主站内核模块交互。通过它可以完成从站扫描、状态管理、过程数据查看、SDO 读写、固件升级、EEPROM 访问等几乎所有主站运维操作。

核心价值

ethercat 工具是日常运维和故障排查的首要工具。掌握它，意味着你可以独立完成 EtherCAT 系统的配置、监控和诊断。

基本用法

基本语法

ethercat <COMMAND> [OPTIONS] [ARGUMENTS]

子命令分类总览（33 个）

分类 命令 简要说明
主站控制 master / debug / rescan / version 主站状态、调试、重扫、版本
从站管理 slaves / alias / states / reboot 从站信息、别名、状态、重启
域管理 domains / data / pcap 域信息、过程数据、抓包
PDO pdos / graph / cstruct PDO 映射、拓扑图、C 结构体
SDO sdos / upload / download 对象字典浏览、SDO 读写
SoE soe_read / soe_write 伺服驱动 IDN 读写
FoE foe_read / foe_write 文件传输（固件升级）
EoE eoe / eoe_addif / eoe_delif / ip 虚拟网络接口管理
SII/EEPROM sii_read / sii_write EEPROM 读写
寄存器 reg_read / reg_write / reg_rdwr ESC 寄存器直接访问
配置 config 从站配置查看
诊断 diag / crc 物理层错误诊断
XML xml 设备描述 XML 导出

技术详情

6.1 编译与安装

ethercat 工具随 IgH EtherCAT Master 一起编译。在执行 make 后，工具二进制文件位于 tool/ethercat。

编译与安装

# 配置（根据平台选择选项）
./configure --prefix=/opt/etherlab

# 编译
make

# 安装
sudo make install

# 添加到 PATH
export PATH=/opt/etherlab/bin:$PATH

# 验证安装
ethercat version

权限说明

ethercat 工具需要通过字符设备 /dev/EtherCAT 与内核模块通信，通常需要 root 权限。可以通过 sudo 运行，或配置 udev 规则授权特定用户组访问。

全局选项

选项 短选项 参数 说明
--master -m <index> 选择主站索引，逗号分隔，支持范围（如 0,2、0-3）。默认 -（全部）
--force -f — 强制执行命令，跳过安全确认
--quiet -q — 减少输出信息
--verbose -v — 输出更多详细信息
--help -h — 显示帮助信息
--alias -a <alias> 按别名选择从站
--position -p <pos> 按位置选择从站
--domain -d <idx> 选择域索引
--type -t <type> 指定数据类型
--output-file -o <file> 输出到文件

命令缩写机制

ethercat 工具支持命令缩写，只要输入的前缀能唯一匹配一个命令即可：

命令缩写示例

ethercat m        # 等同于 ethercat master
ethercat sl       # 等同于 ethercat slaves
ethercat sii_r    # 等同于 ethercat sii_read

匹配规则（按优先级）：1) 精确匹配；2) 前缀匹配；3) 模糊匹配（命令名中任意位置）。

从站选择方式

方式 选项 说明 示例
按位置 -p <pos> 总线上的物理位置（0 起始） -p 0
按别名 -a <alias> EEPROM 中存储的别名 -a 100
全部从站 默认 不指定时操作所有匹配从站 （无选项）

6.2.1 主站命令组 — master / debug / rescan / version

master — 显示主站状态

语法

ethercat master [-m <index>]

显示主站的完整运行状态信息，包括相位、从站数量、以太网设备统计和 DC 状态。日常排查首选命令。

输出示例

$ ethercat master

Master0
  Phase:  Operation
  Active: yes
  Slaves: 3
  Ethernet devices:
    Main: 00:0c:29:12:34:56 (attached)
      Link: UP
      Tx frames:   1234567
      Tx bytes:    74074020
      Rx frames:   1234543
      Rx bytes:    61725415
      Tx frame rate [1/s]:  1000  1000  1000
      Tx rate [KByte/s]:    58    58    58
      Rx frame rate [1/s]:  1000  1000  1000
      Rx rate [KByte/s]:    48    48    48
    Backup: 00:00:00:00:00:00 (waiting)
  Distributed clocks:
    Reference clock:   Slave 0
    Application time:  2026-04-13 10:30:00.123456789

帧速率测量窗口

帧速率以 3 列显示，分别对应最近 3 个统计周期的测量值。值稳定说明通信正常。

debug — 设置调试级别

语法

ethercat debug <LEVEL>
级别 说明 输出位置
0 关闭调试输出（默认） —
1 部分调试：关键状态变更和异常 syslog
2 完全调试：打印所有收发帧内容 syslog

⚠ 性能影响

调试级别 2 会打印所有帧，在高周期率系统中会产生大量日志，影响实时性能。仅临时开启排查问题。

rescan — 触发总线重新扫描

语法

ethercat rescan [-m <index>]

⚠ 数据丢失警告

rescan 会丢弃内核中现有的所有从站信息然后重新读取。生产环境请谨慎使用。

version — 显示工具版本

语法

$ ethercat version
IgH EtherCAT master 1.5.2

纯本地命令，不连接主站设备，无需 root 权限。版本号来自编译时宏 EC_MASTER_VERSION。

6.2.2 从站命令组 — slaves / alias / states / reboot

slaves — 显示从站信息

语法

ethercat slaves [OPTIONS]
选项 缩写 说明
--alias -a 按别名选择从站
--position -p 按位置选择从站
--verbose -v 显示详细信息（端口拓扑、同步管理器、DC 信息）

简要输出

$ ethercat slaves
0  0:0  PREOP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  PREOP  +  EL3102 2Ch. Ana. Input +/-10V
2  0:2  OP     +  EL2004 4Ch. Digital Output 24V

每行格式：位置 别名:位置偏移 AL状态 端口拓扑(+为在线) 产品描述

alias — 设置/读取从站别名

语法

# 读取别名
ethercat alias [OPTIONS]

# 写入别名（需 -f 强制）
ethercat alias [OPTIONS] <ALIAS>

⚠ EEPROM 写入

alias 写入操作会修改从站 EEPROM。写入后需要 ethercat rescan 才能生效。

states — 读取/设置从站 AL 状态

语法

# 读取状态
ethercat states [OPTIONS]
# 设置状态
ethercat states [OPTIONS] <STATE>

状态值：INIT / PREOP / SAFEOP / OP（不区分大小写）

reboot — 重启从站

语法

ethercat reboot [OPTIONS]

⚠ 谨慎操作

reboot 导致从站硬件复位，所有通信中断。从站重启后回到 INIT 状态，需重新配置。

6.2.3 域命令组 — domains / data / pcap

域（Domain）是 IgH 管理过程数据的核心抽象，每个域拥有独立的逻辑地址空间。

domains — 显示域信息

语法

ethercat domains [-d <index>] [-v]

输出示例

Domain0: LogBaseAddr 0x00000000, Size 6, WorkingCounter 0/1

Working Counter 输出格式为 实际值/期望值。不一致时表示从站掉线或配置错误。

data — 输出域过程数据

语法

ethercat data [-d <index>]

将指定域的过程数据以原始二进制形式输出到 stdout。建议配合重定向或管道使用：

示例

ethercat data -d 0 > process_data.bin
ethercat data -d 0 | xxd

pcap — 输出抓包数据

语法

ethercat pcap [-r]

前置条件：主站配置中启用 PCAP_SIZE_MB。

示例

ethercat pcap > capture.pcap
wireshark capture.pcap

6.2.4 PDO 命令组 — pdos / graph / cstruct

pdos — 列出 PDO 映射

语法

ethercat pdos [OPTIONS]
选项 说明
-a/-p 选择从站
-s <skin> 输出样式：default（默认）或 etherlab（MATLAB 格式）
-v 显示 PDO Entry 数据类型和位宽
-q 仅显示 SM 和 PDO 概要

输出示例（-v）

SM3: PhysAddr 0x1100, DefaultSize 0, ControlRegister 0x20, Enable 1
  TxPDO 0x1a00 "Channel1"
    PDO entry 0x3101:01,  8 bit, "Status"
    PDO entry 0x3101:02,  8 bit, "Value"

graph — 输出总线拓扑（DOT 格式）

语法

ethercat graph [DC|CRC] | dot -Tsvg > bus.svg

输出 DOT 语言格式拓扑描述，可通过 Graphviz 渲染为 SVG/PNG。可选参数 DC 附加 DC 时序信息，CRC 附加 CRC 错误统计。

cstruct — 生成 PDO 配置 C 结构体

语法

ethercat cstruct [-a/-p <slave>]

生成三组 C 语言数组（ec_pdo_entry_info_t、ec_pdo_info_t、ec_sync_info_t），可直接用于 ecrt_slave_config_pdos()。

6.2.5 SDO 命令组 — sdos / upload / download

SDO（Service Data Object）用于非周期性参数配置的邮箱通信。从站必须支持 CoE，在 PREOP 状态即可进行 SDO 访问。

sdos — 列出 SDO 对象字典

语法

ethercat sdos [-a/-p <slave>] [-q]

输出示例

SDO 0x1018, "Identity"
  0x1018:00, rwrwrw, uint8, 8 bit, "Number of entries"
  0x1018:01, rwrwrw, uint32, 32 bit, "Vendor ID"
  0x1018:02, rwrwrw, uint32, 32 bit, "Product code"

访问权限格式 rwrwrw：6 个字符，分别表示 PREOP/SAFEOP/OP 三个状态下的读(r)/写(w)权限。

upload — 读取 SDO（从站→主站）

语法

ethercat upload [OPTIONS] <INDEX> [<SUBINDEX>]

示例

# 读取厂商 ID
ethercat upload -p 0 0x1018 0x01

# 以字符串类型读取设备名称
ethercat upload -p 0 -t string 0x1008 0x00

-t 支持类型：int8、int16、int32、int64、uint8、uint16、uint32、uint64、string、raw。

download — 写入 SDO（主站→从站）

语法

ethercat download [OPTIONS] <INDEX> [<SUBINDEX>] <VALUE>

示例

# 设置运行模式为 CSP (值=8)
ethercat download -p 0 0x6060 0x00 8

# 写入十六进制值
ethercat download -p 0 -t uint32 0x8000 0x02 0x12345678

# 从标准输入写入
echo -n "hello" | ethercat download -p 0 -t string 0x1008 0x00 -

6.2.6 SoE 命令组 — soe_read / soe_write

SoE (Servo over EtherCAT) 使用 IDN (Identifier Number) 寻址伺服驱动器参数，由 ETG.5001 规范定义。IDN 是 16 位标识符：

位域 含义
bit15 0 = 标准参数 (S)，1 = 产品参数 (P)
bit14-12 操作数据集编号 (0-7)
bit11-0 数据块编号 (0-4095)

支持字符串格式（S-0-150、P-0-150）和数值格式（0x0096）。

soe_read / soe_write

语法

ethercat soe_read  [OPTIONS] [<DRIVE>] <IDN>
ethercat soe_write [OPTIONS] [<DRIVE>] <IDN> <VALUE>

示例

# 读取
ethercat soe_read -p 0 -t uint16 P-0-150

# 写入（-t 必需）
ethercat soe_write -p 0 -t uint16 P-0-150 100

⚠ soe_write 的 -t 选项是必需的

不指定类型将导致命令报错，因为 SoE 写入操作必须明确数据长度和编码方式。

6.2.7 FoE 命令组 — foe_read / foe_write

FoE (File Access over EtherCAT) 类似 TFTP 的文件传输协议，核心场景是从站固件升级。

foe_read — 从从站读取文件

语法

ethercat foe_read [OPTIONS] <SOURCEFILE> [<PASSWORD>]

示例

# 读取并保存到本地
ethercat foe_read -p 0 firmware.bin -o backup.bin

# 使用密码读取
ethercat foe_read -p 0 firmware.bin 12345 -o backup.bin

foe_write — 向从站写入文件（固件升级）

语法

ethercat foe_write [OPTIONS] <FILENAME> [<PASSWORD>]
参数 说明
<FILENAME> 本地文件路径，- 表示从 stdin 读取
-o <target> 从站侧目标文件名。不指定时使用 FILENAME 的 basename

示例

# 写入固件
ethercat foe_write -p 0 firmware_v2.bin

# 指定从站侧文件名
ethercat foe_write -p 0 my_fw.bin -o firmware.bin

# 从管道写入
cat firmware.bin | ethercat foe_write -p 0 - -o firmware.bin

❌ 危险操作警告

写入不兼容或损坏的固件可能导致从站变砖。执行前务必确认固件兼容、不断电、已备份。

6.2.8 EoE 命令组 — eoe / eoe_addif / eoe_delif / ip

EoE (Ethernet over EtherCAT) 命令组管理通过 EtherCAT 总线传输标准以太网帧的虚拟网络接口。

eoe — 显示 EoE 接口信息

输出示例

$ ethercat eoe
Interface eoe0s0:
  State:   opened
  Rx bytes:   1024
  Rx frames: 10
  Tx bytes:   2048
  Tx frames: 15

eoe_addif / eoe_delif — 创建/删除 EoE 虚拟接口

示例

# 创建
ethercat eoe_addif -p 0

# 配置 IP
sudo ifconfig eoe0s0 192.168.1.1 netmask 255.255.255.0 up

# 删除
ethercat eoe_delif -p 0

ip — 显示/配置 EoE IP 地址

示例

# 查看
ethercat ip -p 0
# 设置
ethercat ip -p 0 192.168.1.100

EoE 网络桥接完整配置案例

桥接配置流程

# 1. 创建 EoE 接口
ethercat eoe_addif -p 0

# 2. 配置 IP
ifconfig eoe0s0 192.168.1.1 netmask 255.255.255.0 up

# 3. 启用 IP 转发
echo 1 > /proc/sys/net/ipv4/ip_forward

# 4. 配置 NAT
iptables -t nat -A POSTROUTING -s 192.168.1.0/24 -o eth0 -j MASQUERADE

编译依赖

EoE 命令仅在编译时启用 EC_EOE 宏时可用（./configure --enable-eoe）。

6.2.9 SII/EEPROM 命令组 — sii_read / sii_write

SII (Slave Information Interface) 命令读写从站 EEPROM，其中存储厂商 ID、产品码、PDO 映射、SM 配置等关键信息。

⚠ 高风险操作

EEPROM 写入具有不可逆性。建议写入前先 sii_read 备份原始数据。

sii_read — 读取 EEPROM

语法

ethercat sii_read [-a/-p <slave>] [-v] [-f]
选项 说明
-v 以分类格式显示 SII 内容（含类别名称）
-f 强制获取 EEPROM 控制权（PDI 释放）

备份 EEPROM

ethercat sii_read -p 0 > slave0_eeprom.bin

sii_write — 写入 EEPROM

语法

ethercat sii_write [-a/-p <slave>] [-f] <FILENAME>

示例

# 恢复备份
ethercat sii_write -p 0 slave0_eeprom.bin

# 从 stdin 写入
cat new_eeprom.bin | ethercat sii_write -p 0 -

6.2.10 寄存器命令组 — reg_read / reg_write / reg_rdwr

直接读写 EtherCAT 从站控制器 (ESC) 的寄存器空间（0x0000–0x0FFF）。最底层的调试手段。

reg_read — 读取寄存器

语法

ethercat reg_read [-a/-p <slave>] [-t <type>] <ADDRESS> [<SIZE>]

reg_write — 写入寄存器

语法

ethercat reg_write [-a/-p <slave>] [-t <type>] [-e] <ADDRESS> <DATA>

reg_rdwr — 原子性读-写操作

语法

ethercat reg_rdwr [-a/-p <slave>] -t <type> <ADDRESS> <DATA>

执行原子性的"先写后读"操作。必须指定 -t 数据类型。

常用寄存器地址速查

地址 名称 大小 读/写
0x0000 ESC 类型/版本 4B R
0x0120 AL 控制寄存器 2B R/W
0x0130 AL 状态寄存器 2B R
0x0134 AL 状态码 2B R
0x0910 DC 系统时间 8B R
0x0E00 厂商 ID 4B R
0x0E04 产品码 4B R
0x0300 错误计数器区域 20B R/W

6.2.11 配置命令 — config

显示主站中已配置的从站配置信息。配置由应用程序通过 ecrt API 创建。

语法

ethercat config [-a/-p <slave>] [-v]

默认输出

$ ethercat config
Alias: 0, Position: 0, Vendor: 0x00000002, Product: 0x044c2c52
  Slave: 0, State: Op
Alias: 0, Position: 1, Vendor: 0x00000002, Product: 0x0c1a3052
  Slave: 1, State: Op

使用 -v 显示完整配置详情（SM/PDO/SDO/IDN/DC）。

6.2.12 诊断命令组 — diag / crc

用于检测和统计 EtherCAT 物理层通信质量，通过读取 ESC 错误寄存器和计数器定位总线信号完整性问题。

diag — ESC 错误诊断

语法

ethercat diag [-a/-p <slave>] [-v] [-r]

输出示例

$ ethercat diag -p 0
Slave 0: DL status: 0x0003
  Port 0: Link=Yes, Comm=Yes
  Port 1: Link=No,  Comm=No

Errors:
  Invalid frame:    0
  RX error:         0
  Forwarded RX error: 0
  Processing error: 0
  Lost link:        0

-r 先清除计数器再读取，用于监控错误增量。

crc — CRC 错误诊断

语法

ethercat crc [-a/-p <slave>] [reset]

输出示例

$ ethercat crc
     CRC  PHY  FWD  NXT|   CRC  PHY  FWD  NXT
0:    12    0    0    0|      0    0    0    0
1:     0    0    0    0|      0    0    0    0

⚠ 计数器溢出

ESC 错误计数器为 8 位宽度，最大值 255，到达上限后停止累加。需定期 crc reset 清零。

6.2.13 XML 命令

从总线上的从站信息生成 EtherCATInfo XML 格式的设备描述文件，可用于 TwinCAT 等配置工具导入。

语法

ethercat xml [-a/-p <slave>]

导出示例

# 导出单个从站 XML
ethercat xml -p 0 > slave0.xml

# 导出所有从站
ethercat xml > all_slaves.xml

6.3 故障排查实战

场景 1：从站无法进入 OP 状态

排查步骤

# 1. 查看从站状态
ethercat slaves

# 2. 读取 AL 状态码
ethercat reg_read -p N -t uint16 0x0134

# 3. 对比配置
ethercat config -p N -v
ethercat pdos -p N -v
flowchart TD A["从站无法进入 OP"] --> B["读取 AL 状态码 reg_read 0x0134"] B --> C{"状态码?"} C -->|"0x0010-0x0012"| D["DC 周期配置错误"] C -->|"0x0018"| E["DC SYNC 未使能"] C -->|"0x001C-0x001E"| F["SM 配置错误<br/>对比 config 与 pdos"] C -->|"0x0020-0x0022"| G["PDO 映射错误"] C -->|"0x0000"| H["检查缺少的强制 SDO"]

场景 2：Working Counter 异常

排查步骤

ethercat domains     # 检查 WKC
ethercat slaves       # 确认从站状态
ethercat pdos -p N -v # 检查 PDO 映射

场景 3：DC 同步丢失

排查步骤

ethercat master       # DC 状态
ethercat slaves -p N -v # 从站 DC 详情
ethercat crc           # 物理层错误

场景 4：通信超时

排查步骤

ethercat diag         # 错误统计
ethercat crc           # CRC 错误
ethercat crc reset     # 清零后观察增量
ethercat graph | dot -Tsvg > topology.svg

场景 5：邮箱通信失败

排查步骤

ethercat slaves                    # 确认 ≥ PREOP
ethercat reg_read -p N 0x0800 12   # 检查邮箱 SM 配置
ethercat upload -p N 0x1018 0x01   # 测试 SDO 读

诊断命令速查表

排查方向 命令 关键输出
总线状态 ethercat master Phase、DC 状态
从站状态 ethercat slaves AL 状态、错误标志
域 WKC ethercat domains WorkingCounter
配置对比 ethercat config -p N -v 请求配置 vs 实际
物理层 ethercat crc 端口 CRC/PHY/FWD
AL 状态码 ethercat reg_read -p N 0x0134 2 具体错误原因

排障黄金法则

  1. 先看状态：ethercat slaves 确认从站状态
  2. 再看 WKC：ethercat domains 确认 WKC 正常
  3. 逐级排查：物理层 → 链路层 → 协议层 → 应用层
  4. 善用复位：crc reset / diag -r 清零后观察增量
  5. 对比配置：config -v 与 pdos -v 对比请求和实际配置

深入源码

工具源码架构

文件 职责
main.cpp 程序入口：解析全局选项、匹配子命令、分发执行
Command.h/cpp 命令基类：定义 helpString()、execute() 接口
Command*.h/cpp 33+ 个子命令实现
MasterDevice.h/cpp 封装 ioctl 系统调用
SdoCommand.h/cpp SDO 命令公共基类（upload/download 复用）
SoeCommand.h/cpp SoE 命令公共基类（IDN 解析/错误处理）
FoeCommand.h/cpp FoE 命令公共基类（文件数据加载）

命令注册与匹配

main.cpp 中注册所有命令对象，通过 getMatchingCommands() 实现三级匹配策略：

flowchart TD A["输入命令字符串"] --> B{"精确匹配?"} B -->|是| C["返回唯一结果"] B -->|否| D{"前缀匹配?"} D -->|是且唯一| C D -->|是但不唯一| E["报错: 命令歧义"] D -->|否| F{"模糊匹配?"} F -->|是且唯一| C F -->|是但不唯一| E F -->|否| G["报错: 未知命令"]

通信架构

ethercat 工具通过 ioctl 系统调用与内核主站模块通信：

flowchart LR CL["ethercat<br/>命令行工具"] -->|ioctl| CD["/dev/EtherCAT<br/>字符设备"] CD --> KM["ec_master<br/>内核主站模块"] KM -->|EtherCAT 帧| BUS["EtherCAT 总线"]

命令基类接口

方法 说明
getName() 返回命令名称字符串
getBriefDescription() 返回简要描述
helpString(binaryName) 返回完整帮助文本（纯虚函数）
execute(args) 执行命令逻辑（纯虚函数）

MasterDevice 通信层关键 ioctl

方法 对应 ioctl 说明
getMaster(&data) EC_IOCTL_MASTER 获取主站信息
getSlave(&data, idx) EC_IOCTL_SLAVE 获取从站信息
getConfig(&data, idx) EC_IOCTL_CONFIG 获取从站配置
getDomain(&data, idx) EC_IOCTL_DOMAIN 获取域信息
sdoUpload(&req) EC_IOCTL_SDO_REQUEST SDO 上传
sdoDownload(&req) EC_IOCTL_SDO_REQUEST SDO 下载
readSii() / writeSii() EC_IOCTL_SII_* EEPROM 操作
soeRead() / soeWrite() EC_IOCTL_SOE_* SoE 操作
foeRead() / foeWrite() EC_IOCTL_FOE_* FoE 操作

命令打开模式一览

模式 命令 说明
无连接 version 不打开设备，直接输出版本
Read master, slaves, domains, pdos, sdos, upload, config, diag, crc, xml, graph, cstruct, data, eoe 只读打开
ReadWrite debug, rescan, alias(写), states(设置), download, soe_write, foe_write, foe_read, sii_write, reg_write, reg_rdwr, eoe_addif, eoe_delif, ip(设置), reboot 读写打开
posted @ 2026-04-14 22:04  沐多  阅读(568)  评论(0)    收藏  举报