ethercat igh tool工具使用

重要提示:

• 权限: 许多命令（特别是写入操作、状态更改、加载/卸载模块等）需要 root 权限。请在需要时使用 sudo 执行命令。
• 主站运行: ethercat 工具需要 EtherCAT 主站服务正在运行。您通常可以使用 sudo systemctl start ethercat 或 sudo /etc/init.d/ethercat start 来启动服务，并使用 status 查看状态。
• 从站位置/别名: 大多数针对特定从站的命令都需要通过 -p <position> (位置，从 0 开始) 或 -a <alias> (别名，如果已设置) 来指定目标从站。
• 获取帮助: 对于每个命令，您都可以使用 -h 或 --help 选项来查看其具体参数和用法，例如 ethercat slaves -h。这是获取最准确信息的最佳途径，因为具体选项可能随版本微调。
• 命令缩写: 列表提到命令可以缩写，这意味着您可能可以使用命令的前几个唯一字母，例如用 ethercat sl 代替 ethercat slaves。

---

ethercat 命令行工具手册

基本语法:

ethercat <COMMAND> [OPTIONS] [ARGUMENTS]

---

命令详解:

1. master

• 描述: 显示主站和以太网设备信息。
• 用途: 查看主站状态、活动状态、连接的从站数量以及主站绑定的网络接口。
• 常见用法:

  ethercat master
  

• 示例输出 (可能类似):

  Master0
    Phase: Idle
    Active: no
    Slaves: 0
    Ethernet devices:
      Main: e4:5d:2e:aa:bb:cc (attached)
        Link: Unknown
        Tx frames: 0
        Rx frames: 0
        Tx bytes: 0
        Rx bytes: 0
  

2. slaves

• 描述: 显示总线上的从站。
• 用途: 列出当前连接到 EtherCAT 总线上的所有从站及其状态。
• 常见用法:

  ethercat slaves [-v] # 列出所有从站，-v 显示更详细信息
  ethercat slaves -p <position> [-v] # 显示指定位置的从站信息
  ethercat slaves -a <alias> [-v]  # 显示指定别名的从站信息
  

• 示例:

  ethercat slaves
  ethercat slaves -p 0 -v # 查看位置 0 从站的详细信息
  

• 输出: 通常会显示从站的位置、别名（如果有）、名称、状态 (如 OP, SAFEOP, PREOP, INIT, BOOT) 和标志。

3. upload

• 描述: 从从站读取一个 SDO 条目。
• 用途: 读取从站对象字典 (Object Dictionary) 中的特定条目的值。
• 常见用法 (具体选项请用 -h 确认):

  ethercat upload -p <position>|< -a <alias>> <index> <subindex> [--type <datatype>]
  ``` *   `<index>`: SDO 索引 (十六进制, e.g., `0x6040`)
  *   `<subindex>`: SDO 子索引 (十进制, e.g., `0`)
  *   `--type <datatype>`: (可能需要) 指定期望读取的数据类型 (e.g., `uint16`, `int32`, `string`)。**请务必用 `ethercat upload -h` 确认此选项是否存在及如何指定类型。** 如果没有 `--type`，可能需要其他方式指定或工具会尝试自动检测。
  

• 示例:

  # 读取位置 1 从站的对象 0x1008 (设备名称) 子索引 0 (通常是字符串)
  ethercat upload -p 1 0x1008 0 --type string
  
  # 读取位置 0 从站的对象 0x6041 (状态字) 子索引 0 (通常是 uint16)
  ethercat upload -p 0 0x6041 0 --type uint16
  

4. download

• 描述: 向从站写入一个 SDO 条目。
• 用途: 修改从站对象字典中特定条目的值。通常需要 sudo 权限。
• 常见用法 (具体选项请用 -h 确认):

  sudo ethercat download -p <position>|< -a <alias>> <index> <subindex> [--type <datatype>] <value_or_file>
  

  • <value_or_file>: 要写入的值，或包含数据的文件的路径。值的格式需要与数据类型匹配。请务必用 ethercat download -h 确认如何提供值以及是否需要 --type。
• 示例:

  # 向位置 0 从站的对象 0x6040 (控制字) 子索引 0 写入 uint16 值 6 (Shutdown)
  sudo ethercat download -p 0 0x6040 0 --type uint16 6
  
  # 向位置 0 从站的对象 0x6040 (控制字) 子索引 0 写入 uint16 值 15 (Enable Operation)
  sudo ethercat download -p 0 0x6040 0 --type uint16 15
  
  # (假设) 从文件写入对象 0x1F51 子索引 1
  # sudo ethercat download -p 1 0x1F51 1 /path/to/datafile
  

5. sdos

• 描述: 列出 SDO 字典。
• 用途: 显示指定从站对象字典中可用的 SDO 条目列表（索引、子索引、名称、数据类型等）。
• 常见用法:

  ethercat sdos -p <position> |< -a <alias>>
  

• 示例:

  ethercat sdos -p 0 # 列出位置 0 从站的所有 SDO 条目
  

6. pdos

• 描述: 列出同步管理器 (Sync managers)、PDO 分配 (PDO assignment) 和映射 (mapping)。
• 用途: 查看从站的过程数据对象 (PDO) 配置，包括哪些对象被映射到了过程数据中，以及它们是如何组织的。
• 常见用法:

  ethercat pdos [-v] # 列出所有从站的 PDO 信息
  ethercat pdos -p <position> |< -a <alias>> [-v] # 列出指定从站的 PDO 信息
  

• 示例:

  ethercat pdos -p 0 -v # 查看位置 0 从站的详细 PDO 信息
  

7. states

• 描述: 请求应用层状态。
• 用途: 读取或设置一个或所有从站的 EtherCAT 状态机状态 (如 INIT, PREOP, SAFEOP, OP)。
• 常见用法:

  ethercat states # 读取所有从站的当前状态
  sudo ethercat states <STATE> # 请求将所有从站设置到 <STATE>
  sudo ethercat states -p <position> |< -a <alias>> <STATE> # 请求将指定从站设置到 <STATE>
  

  • <STATE>: 目标状态，如 INIT, PREOP, SAFEOP, OP, BOOT。
• 示例:

  ethercat states # 查看当前状态
  sudo ethercat states OP # 尝试将所有从站设为 OP 状态
  sudo ethercat states -p 0 SAFEOP # 将位置 0 的从站设为 SAFEOP 状态
  ```*   **注意:** 状态转换必须遵循 EtherCAT 状态机规则 (e.g., 不能直接从 `INIT` 到 `OP`)。设置状态需要 `sudo` 权限。
  
  

8. config

• 描述: 显示从站配置。
• 用途: 显示从站的详细配置信息，可能包括供应商 ID、产品代码、PDO 配置、邮箱配置等。
• 常见用法:

  ethercat config -p <position> |< -a <alias>> [-v]
  

• 示例:

  ethercat config -p 0 -v # 显示位置 0 从站的详细配置
  

9. cstruct

• 描述: 以 C 语言生成从站 PDO 信息。
• 用途: 根据当前总线配置，生成包含 PDO 变量偏移量和数据类型的 C 语言头文件内容，方便应用程序直接访问过程数据。
• 常见用法:

  ethercat cstruct > my_ethercat_config.h # 将生成的 C 结构体输出到文件
  

• 输出: C 语言代码，通常包含宏定义和结构体定义。

10. domains

• 描述: 显示配置的域。
• 用途: 列出主站中配置的过程数据域 (Domains)，以及哪些从站的 PDO 被映射到了这些域中。域用于组织和访问过程数据。
• 常见用法:

  ethercat domains [-v]
  

11. alias

• 描述: 写入别名地址。
• 用途: 为总线上的特定位置的从站设置一个固定的别名地址。这在从站位置可能改变时很有用，可以通过别名而不是物理位置来寻址。通常需要 sudo 权限。
• 常见用法 (语法需用 -h 确认):

  sudo ethercat alias -p <position> <alias_address>
  

  • <alias_address>: 要设置的别名 (一个数字)。
• 示例:

  sudo ethercat alias -p 0 1001 # 为位置 0 的从站设置别名 1001
  

12. reg_read / reg_write / reg_rdwr

• 描述: 读取 (reg_read)、写入 (reg_write) 或读写 (reg_rdwr) 从站的寄存器。
• 用途: 直接访问 EtherCAT 从站控制器 (ESC) 的内部寄存器。这通常用于低级调试或特殊配置。写入需要 sudo 权限。
• 常见用法 (语法需用 -h 确认):

  ethercat reg_read -p <pos> <addr> [--type <dtype>]
  sudo ethercat reg_write -p <pos> <addr> [--type <dtype>] <value>
  sudo ethercat reg_rdwr -p <pos> <addr> [--type <dtype>] <value> # 可能先读后写
  

  • <addr>: 寄存器地址 (十六进制, e.g., 0x0100)。
  • --type <dtype>: 数据类型 (e.g., uint8, uint16, uint32)。
• 示例:

  ethercat reg_read -p 0 0x0000 --type uint16 # 读取位置 0 从站的 ESC 类型寄存器
  sudo ethercat reg_write -p 1 0x0502 --type uint8 1 # 向位置 1 从站的某个寄存器写值
  

• 警告: 直接写寄存器可能导致从站行为异常或总线中断，请谨慎使用。

13. sii_read / sii_write

• 描述: 读取 (sii_read) 或写入 (sii_write) 从站的 SII (Slave Information Interface) 内容。
• 用途: 访问或修改存储在从站 EEPROM 中的信息（设备信息、配置数据等）。写入 (sii_write) 非常危险，可能损坏从站，需要 sudo 权限，并谨慎使用。
• 常见用法:

  ethercat sii_read -p <position> |< -a <alias>> [--output <filename>]
  sudo ethercat sii_write -p <position> |< -a <alias>> <filename>
  

• 示例:

  ethercat sii_read -p 0 -o slave0_sii.bin # 将位置 0 从站的 SII 内容读出到文件
  # sudo ethercat sii_write -p 0 slave0_sii_modified.bin # (危险!) 从文件写入 SII
  

14. version

• 描述: 显示版本信息。
• 用途: 显示 EtherCAT Master 软件的版本号。
• 常见用法:

  ethercat version
  

15. graph

• 描述: 以图形方式输出总线拓扑。
• 用途: 生成描述当前 EtherCAT 总线连接拓扑的文本表示（通常是 DOT 语言格式）。
• 常见用法:

  ethercat graph > topology.dot # 将输出保存到文件
  

• 注意: 您可以使用 Graphviz 工具包中的 dot 命令将 .dot 文件转换为图像 (e.g., dot -Tpng topology.dot -o topology.png)。

16. xml

• 描述: 生成从站信息 XML。
• 用途: 输出描述总线上所有从站信息的 XML 文件。这可以用于自动化配置或与其他工具集成。
• 常见用法:

  ethercat xml > slaves_info.xml
  

17. data

• 描述: 输出二进制域过程数据。
• 用途: 将当前过程数据域的内容以二进制格式转储到标准输出或文件。用于调试或记录实时数据。
• 常见用法 (语法需用 -h 确认):

  ethercat data [--domain <index>] [--output <filename>]
  

18. pcap

• 描述: 输出二进制 pcap 捕获数据。
• 用途: 将底层的 EtherCAT 帧捕获为 pcap 格式，可以使用 Wireshark 等网络分析工具进行查看。
• 常见用法 (语法需用 -h 确认):

  ethercat pcap [--output <filename.pcap>]
  

19. foe_read / foe_write

• 描述: 通过 FoE (File access over EtherCAT) 从从站读取文件 (foe_read) 或向从站存储文件 (foe_write)。
• 用途: 用于传输固件、配置文件等到支持 FoE 协议的从站。写入需要 sudo 权限。
• 常见用法 (语法需用 -h 确认):

  ethercat foe_read -p <pos> <slave_filename> [<local_filename>]
  sudo ethercat foe_write -p <pos> <local_filename> [<slave_filename>] [--password <pwd>]
  

20. soe_read / soe_write

• 描述: 从从站读取 (soe_read) 或写入 (soe_write) SoE (Servo drive profile over EtherCAT) IDN。
• 用途: 与支持 SoE 协议的伺服驱动器进行参数读写。写入需要 sudo 权限。
• 常见用法 (语法需用 -h 确认):

  ethercat soe_read -p <pos> <idn>
  sudo ethercat soe_write -p <pos> <idn> <value> [--type <dtype>]
  

21. eoe / eoe_addif / eoe_delif / ip

• 描述: 与 EoE (Ethernet over EtherCAT) 相关的功能。
  • eoe: 显示 EoE 统计信息。
  • eoe_addif: 添加 EoE 虚拟网络接口。(sudo 需要)
  • eoe_delif: 删除 EoE 虚拟网络接口。(sudo 需要)
  • ip: 设置 EoE IP 参数 (可能针对从站的 EoE 配置)。(sudo 需要)
• 用途: 允许标准的以太网协议通过 EtherCAT 总线传输，例如为从站设置 IP 地址或访问其内部 Web 服务器。具体用法请参考 -h。

22. diag

• 描述: 输出从站的 ESC (EtherCAT Slave Controller) 错误寄存器。
• 用途: 读取从站的错误计数器和状态寄存器，用于诊断通信问题。
• 常见用法:

  ethercat diag [-p <pos>]
  

23. crc

• 描述: CRC 错误寄存器诊断。
• 用途: 专门检查 EtherCAT 端口的 CRC (Cyclic Redundancy Check) 错误计数器，帮助定位物理层连接问题。
• 常见用法:

  ethercat crc [-p <pos>]
  

24. debug

• 描述: 设置主站的调试级别。
• 用途: 调整 EtherCAT 主站内核模块输出的调试信息的详细程度。需要 sudo 权限。
• 常见用法:

  sudo ethercat debug <level>
  

  • <level>: 通常是一个数字，0 表示关闭调试信息，更高的数字表示更详细的输出。

25. reboot

• 描述: 请求设备硬件重启。
• 用途: 向支持此功能的从站发送命令，请求其进行硬件重启。需要 sudo 权限。
• 常见用法:

  sudo ethercat reboot -p <pos>
  

26. rescan

• 描述: 重新扫描总线。
• 用途: 让主站重新扫描 EtherCAT 总线，检测连接的从站拓扑结构的变化。需要 sudo 权限。
• 常见用法:

  sudo ethercat rescan
  

---

希望这份详细的手册能帮助您更好地使用 ethercat 命令行工具！记得在实际操作中结合 -h 选项获取最准确的参数信息。