跳到主要内容

Java SDK 概述

EtherCAT 主站类库，用于 Web 后端 / 企业系统集成。PascalCase 无前缀命名，对齐 C#。

安装​

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

环境要求​

  • 操作系统 — Windows 10/11 (最低 Windows 7+)
  • Java — JDK 11+ (推荐 JDK 17 LTS)
  • 权限 — 管理员
  • 实时内核驱动 — 微秒级实时性能所需，随安装包提供，见 Windows 驱动

快速开始​

用 Darra 配置工具扫描网络、配置从站、导出 DENI 文件，代码中一行加载：

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 时)​

用 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 无前缀（对齐 C#），不用 get/set：master.SlaveCount() / slave.Name() / slave.CoE()。不变值用 public final 字段：slave.SlaveNum / master.MasterIndex。

高级 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 特有语法糖​

com.darra.ethercat.sugar 包提供一组可选扩展（不影响标准 API）：try-with-resources、Stream<Slave> / Optional<Slave> / Iterable for-each、CompletableFuture<T> 异步、BlockingQueue<EmergencyEvent> 诊断队列、record 不可变身份、lambda listener、MasterBuilder 流式构造器。详见 Java 特有语法糖。

自动健康检查​

master.Build() 启动时自动校验驱动版本与 RT 核隔离，不匹配写 Warning。

错误码本地化​

AL Status 描述支持中英双语（默认英文，UI 可取中文）：

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

版本兼容​

当前 SDK 版本 2.7.x。PATCH 兼容、MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。