跳到主要内容

Java SDK 概述

Darra EtherCAT Java SDK 提供了用于开发 EtherCAT 主站应用程序的类库，支持主站与从站之间的高速实时通信。

安装​

<dependency>
    <groupId>xyz.darra</groupId>
    <artifactId>darra-ethercat-master</artifactId>
    <version>2.7.0</version>
</dependency>

系统要求​

项目要求
操作系统Windows 7+ (推荐 Windows 10/11)
JavaJDK 11+ (推荐 JDK 17 LTS)
网络适配器常规以太网网卡
权限管理员权限

安装 DarraRT 驱动​

DarraRT 驱动提供微秒级实时性能，完全免费。详见 下载页面。

快速开始​

使用 Darra 配置工具
  1. 打开 Darra 配置工具，扫描 EtherCAT 网络
  2. 配置从站参数（PDO 映射、DC 设置等）
  3. 导出 JSON 配置文件
  4. 在代码中加载 JSON 文件初始化主站
import com.darra.ethercat.master.EtherCATMaster;
import com.darra.ethercat.data.EcState;

// ★ 推荐方式: 使用 DENI 文件 (Darra 配置工具一键导出)
EtherCATMaster.BuildResult r = EtherCATMaster.create()
    .setENI("C:/EtherCAT/MyProject.deni")
    .build();
if (!r.success) throw new RuntimeException(r.message);

try (EtherCATMaster master = r.master) {
    master.setState(EcState.OP);
    // 开始通信...
}  // 自动 close() 释放资源

备选方式: 自动搜索网卡 (无 DENI 时)​

不使用 DENI 时, 用 NetworkInfo.getAvailableNetworks() 自动扫描所有网卡, 取有从站的那张:

import com.darra.ethercat.master.EtherCATMaster;
import com.darra.ethercat.statics.NetworkInfo;
import com.darra.ethercat.data.EcState;
import java.util.List;

// 扫所有 NIC 并探测从站数 (耗时 ~500ms-1.5s)
List<NetworkInfo> nets = NetworkInfo.getAvailableNetworks(false, true);

// 选有从站的 NIC
NetworkInfo ec = nets.stream()
    .filter(n -> n.getSlaveCount() != null && n.getSlaveCount() > 0)
    .findFirst()
    .orElseThrow(() -> new RuntimeException("未发现 EtherCAT 网络"));
System.out.printf("找到: %s (从站 %d 台, MAC=%s)%n",
    ec.getDescription(), ec.getSlaveCount(), ec.getMacAddress());

try (EtherCATMaster master = EtherCATMaster.create()) {
    master.setNetwork(ec.getName(), null);
    master.setState(EcState.OP);
}
何时用哪种
  • DENI — 生产环境, 一行加载 ESI/PDO/DC 全套参数, 推荐.
  • 自动搜索 — 演示 / 工具类应用 / 不需要预配置启动参数的场景.
PascalCase 命名风格

Java SDK 采用 PascalCase 无前缀 的属性方法命名（对齐 C#），不使用 get/set 前缀。例：master.SlaveCount() / slave.Name() / slave.CoE()。不变值用 public final 字段：slave.SlaveNum / master.MasterIndex。

高级 API​

SDK 提供了一组高级 API，简化常见操作流程：

功能说明
JSON 一步初始化createFromJson() / createFromJsonFile() 一步完成主站初始化
状态链转换 (setState)自动执行多步状态转换链
CiA 402 驱动状态机一步使能/故障复位/状态解析
EMCY 紧急消息缓冲读取从站紧急消息历史记录
PDO 零拷贝读写通过 ByteBuffer 直接读写 PDO 数据
拓扑查询构建并查询从站网络拓扑树
WDK 实时驱动微秒级 PDO 周期
冗余网络双网卡环形冗余

快速示例:

// CiA402 驱动器使能
slave.CiA402().Enable();

// 类型化 SDO 读写
Integer pos = slave.CoE().SDOReadInt32((short) 0x6064, (byte) 0);
slave.CoE().SDOWriteInt32((short) 0x607A, (byte) 0, 100000);

// 读取紧急消息
List<CoE.EmergencyMessage> history = slave.CoE().GetEmergencyHistory();

// 拓扑查询
List<Integer> children = master.TopologyChildren(parentIdx);

2.5.x 版本新增​

功能说明
MDP 模块化设备自动编排进 OP 时自动检测并配置模块化设备（GCAN-8200 等），详见 MDP
邮箱统计7 个邮箱协议（CoE/FoE/SoE/AoE/EoE/VoE/FSoE）的 getStatistics() / resetStatistics() 接通真实 native 统计（此前为占位）
异步邮箱事务DarraCore.EcxMbxSubmitAsync / EcxMbxWait / EcxMbxCancel / EcxMbxGetResult 异步邮箱事务原语
从站实时状态镜像slave.WcContributed() / slave.AlStatusMirror() / slave.IsLost() 零帧实时读取内核 per-slave 状态镜像，详见 从站诊断
SERCOS IDN 编解码SoE.encodeIdn / decodeIdn / tryParseSercosIdn
ESI DC 能力门slave.DC().dcSyncModeFromEsi() / hasEsiDcSync() 走 ESI 真实声明的 DC OpMode

Java 特有语法糖​

除标准 API 外, Java SDK 在 com.darra.ethercat.sugar 包提供一组利用 Java 语言特性的可选扩展, 让代码更简洁. 详见 Java 特有语法糖 — 包含 try-with-resources / Stream<Slave> 流式 / Optional<Slave> null safety / Iterable for-each / CompletableFuture<T> 异步 / BlockingQueue<EmergencyEvent> 诊断队列 / record 不可变身份 / Functional listener (lambda) / MasterBuilder 流式构造器. 这些是可选的, 不影响标准 API 使用.

自动健康检查 · Auto health checks​

master.Build() 时自动跑, 不匹配 → SDK 日志 Warning:

  • 驱动版本比对 — SDK 查询底层实时驱动的内核版本, 跟 SDK 的 MAJOR.MINOR 比对, 不一致即告警
  • RT 核隔离 — 后台检查实时核隔离配置标记, 缺失提示重装 SDK

错误码本地化 · Error localization​

AL Status 描述双语. SDK 默认英文, 中文专用接口给 UI: 

String en = PrintHelper.getALStatusDescription(code);          // English
String zh = PrintHelper.getALStatusDescriptionChinese(code);  // 中文
DriverVersionInfo drv = DriverVersionHelper.get();             // 内核驱动版本

版本兼容​

  • 同 MAJOR.MINOR 内 PATCH 互相兼容 (例 2.7.0 ↔ 2.7.5), 包管理器升级即可, 不需重装驱动
  • MAJOR / MINOR 变化 → 必须重装配套的驱动安装包, 否则会报版本兼容错误