Darra EtherCAT Master · Rust SDK

商业 EtherCAT 主站协议栈 · 实时内核驱动 · 抖动 ≤ 1 µs Commercial EtherCAT Master protocol stack · Real-time kernel driver · ≤ 1 µs jitter

[ Windows x64 ] [ 多编程语言 ] [ 全协议 ] [ 支持复杂拓扑 + 热插拔 ] [ ethercat.darra.xyz ]

为什么选 Darra · Why Darra

	传统 EtherCAT 方案	Darra EtherCAT
形态 / Form	专用控制卡 + 专用 PC	纯软件方案 + 实时内核驱动
平台 / Platform	专用 RTOS 或 Windows	Windows x64
SDK 语言 / Languages	1–2 种	6 种字节级一致 (C / C++ / C# / Java / Python / Rust)
协议覆盖 / Protocols	部分	全协议: CoE · EoE · FoE · SoE · AoE · VoE · FSoE (SIL3)
周期 / 抖动	0.5–10 ms / >10 µs	50 µs 周期 / ≤ 1 µs 抖动 (配 DarraRT)
部署 / Deployment	专用硬件 + 重型 IDE	一行 `cargo add`
文档 / Docs	散乱 PDF	完善的在线 SDK 文档

核心能力 · Key capabilities

三种初始化方式 (按场景选):

🟢 DENI 文件 (★ 生产推荐) — Darra 配置工具一键导出, ESI/PDO/DC/启动参数全套预配置, 1 行加载.
🟡 ESI 目录 + 自动配 — 给 ESI 库 (SetEsiFiles(dir) + EnableAutoStartup()), SDK 按从站身份自动套默认 PDO/SM 参数.
🟠 纯自动配 — 没 ESI 也行, 用从站自带 CoE 对象字典自动配 (调试 / 演示场景).

高级 API 简化常见流程:

一步初始化 EcInit(json) / EcInitFromFile(path) — 把 Initialize + SetNetwork + LoadConfig + SetStateSequence + Start 五步一行解决.
状态链 SetState(OP) — 自动 INIT → PreOp → SafeOp → OP, 失败自动回退诊断.
启动参数管线 AddStartupParameter / Apply — 批量添加 SDO 启动参数, 状态切换时一次写入.
CiA402 驱动状态机 — 一行使能 / 故障复位, 自动解析驱动状态字 (Switch on / Operation enabled / Fault).
EMCY 紧急消息缓冲 — 读取从站紧急消息历史 (Emergency Recorder).
PDO 类型化读写 — 按 U16 / I32 / F32 / 结构体直接读写, 自动字节序处理.
拓扑查询 — 实时构建从站网络拓扑树, 含分支 / 环识别.

底层协议与可靠性:

CoE / EoE / FoE / SoE / AoE / VoE / FSoE (SIL3) — 全协议覆盖.
DC 分布式时钟 — ≤ 1 µs 同步, 静态 + 动态偏移补偿.
Hot-Connect + 冗余 — 单周期切换, 环 / 分支拓扑.
邮箱网关 (ETG.8200) — TwinCAT / 第三方工具透传.
诊断 (ETG.1510) — 32-bit CRC + 断线定位 + AL Status 解析 + 紧急消息历史.

Install

[dependencies]
darra-ethercat-master = "*"

cargo add darra-ethercat-master

可选 features: async-tokio / redundancy / udp / wdk

要求: Rust 1.70+ · Windows 10/11 x64 · 首次运行需以管理员安装 DarraRT 实时内核驱动.

快捷使用 · Quick start

最简流程: DENI 一行加载 → 进 OP → 邮箱基本读写.

use darra_ethercat::{EtherCATMaster, EcState};

fn main() -> darra_ethercat::Result<()> {
    let master = EtherCATMaster::builder()
        .set_eni(r"C:\EtherCAT\MyProject.deni")     // DENI 一行加载
        .build()?;

    master.set_state_sequence(EcState::Operational, 10_000)?;  // 自动 INIT → PreOp → SafeOp → OP

    let slave = master.slave(1);

    // 邮箱读 — 两种风格任选:

    //  ① 基本: Vec<u8> + 手动解析
    let data = slave.coe().sdo_read(0x6041, 0x00, false)?;
    let statusword = u16::from_le_bytes([data[0], data[1]]);

    //  ② 高级: 标准库零拷贝类型化 (一行)
    let sw = u16::from_le_bytes(
        slave.coe().sdo_read(0x6041, 0x00, false)?[..2].try_into().unwrap()
    );

    // 邮箱基本写: 字节版
    slave.coe().sdo_write(0x607A, 0x00, false, &100_000i32.to_le_bytes())?;

    Ok(())
}

高级使用 · Advanced

自动搜网卡 + ESI 自动配 · CiA402 / 邮箱网关 / 诊断.

use darra_ethercat::{EtherCATMaster, EcState};
use darra_ethercat::statics::network::enumerate_network_info;

fn main() -> darra_ethercat::Result<()> {
    // ① 自动搜网卡 (取有从站的那张 NIC)
    let nets = enumerate_network_info(false, true);
    let ec = nets.iter().find(|n| n.slave_num > 0)
        .expect("未发现 EtherCAT 网络");

    // ② ESI 目录 + 自动配 (无 DENI 场景)
    let master = EtherCATMaster::builder()
        .set_esi_files(r"C:\Esi")
        .set_network(&ec.name, "")
        .enable_auto_startup()
        .build()?;

    master.set_state_sequence(EcState::Operational, 10_000)?;

    // ③ 异步 SDO 写 (启用 async-tokio feature 时)
    #[cfg(feature = "async-tokio")]
    master.slave(1).coe()
        .sdo_write_async(0x607A, 0x00, false, &100_000i32.to_le_bytes())
        .await?;

    Ok(())
}

更多 API · More APIs — 完整参考: https://ethercat.darra.xyz/docs/sdk/rust

6 语言 SDK 家族 · 6-language SDK family

字节级一致的 CRC / 枚举 / 错误码,业务代码可平滑跨语言。

Language	Package	Registry
Rust	`darra-ethercat-master`	crates.io
C#	`Darra.EtherCAT.Master`	NuGet
Python	`darra-ethercat-master`	PyPI
Java	`xyz.darra:darra-ethercat-master`	Maven Central
C / C++	`darra-ethercat-c` / `darra-ethercat-cpp`	Releases

文档 · Documentation

官网 · Homepage: https://ethercat.darra.xyz
Rust SDK 文档: https://ethercat.darra.xyz/docs/sdk/rust
快速开始: https://ethercat.darra.xyz/docs/quick-start
协议详解: https://ethercat.darra.xyz/docs/ethercat
应用案例: https://ethercat.darra.xyz/docs/examples

⚠️ 关于"微秒级"实时性能 · About microsecond real-time 本 SDK 强制配合 DarraRT 实时内核驱动 + 兼容硬件 使用. 微秒级实时由 SDK + DarraRT 共同提供. DarraRT 通过 CPU 核心隔离 + I/O APIC 中断重定向 + LVT 屏蔽 + 干净抖动统计 显著降低 SMI 干扰 (但不能完全抑制, SMM 属硬件层中断, 完全抑制需 BIOS/UEFI 配合). DarraRT 需另行安装 (非自动安装); SDK 启动时若未检测到, 会提示获取下载链接. 我们另提供 硬实时隔离部署方案, 满足更严苛的实时与功能安全需求. 详见 DarraRT 驱动说明.

This SDK requires the DarraRT real-time kernel driver and supported hardware as runtime companions. Microsecond-level performance is delivered by SDK + DarraRT together. DarraRT mitigates SMI via CPU core isolation, I/O APIC redirect, LVT masking, and clean jitter accounting, though it cannot fully suppress SMI (SMM is a hardware-level interrupt; full suppression requires BIOS/UEFI tuning). DarraRT must be installed separately (not auto-installed); the SDK prompts a download link on startup if not detected. A hard real-time isolated deployment is also available for stricter real-time and functional-safety requirements.

darra-ethercat-master 1.99.5