<p align="center"><img src="https://download.darra.xyz/ethercat/static/icon.png" alt="Darra EtherCAT Master" width="96" height="96"></p>

# Darra EtherCAT Master · Rust SDK

> **商业 EtherCAT 主站协议栈 · 功能齐全 · 易于集成 · 高可靠**
> *Commercial EtherCAT master protocol stack · Feature-complete · Easy to integrate · High reliability*

`[ Windows · Linux · MCU ]`  `[ 6 语言 SDK / 6 languages ]`  `[ 全协议含 FSoE / Full mailbox + FSoE ]`  `[ 冗余 + 热插拔 + 三级自愈 / Redundancy + hot-plug + 3-level recovery ]`  `[ ethercat.darra.xyz ]`

---

## 为什么选 Darra

围绕三件事打磨:**功能齐全 · 使用方便 · 高可靠**.

|  | SOEM 开源 | 专用主站板卡 | **Darra EtherCAT** |
|---|---|---|---|
| **— 功能齐全 —** | | | |
| 邮箱协议 | CoE / EoE / FoE | 视厂商 | **全 7 协议**: CoE · EoE · FoE · SoE · AoE · VoE · **FSoE (SIL3)** |
| 高级特性 | DC, 冗余需自实现 | 视厂商 | **DC + Hot-Connect + 邮箱网关 (ETG.8200) + CiA402 状态机** |
| 拓扑 | 线 / 树 | 视厂商 | **线 / 树 / 环 / 分支 / 星 + 热插拔** |
| **— 使用方便 —** | | | |
| SDK 语言 | C 一种 | 厂商专用 SDK | **6 种字节级一致** (C / C++ / C# / Java / Python / Rust) |
| 安装 | 自行编译集成 | 配套硬件 + 厂商 IDE | **包管理器一行**: `dotnet add` / `pip install` / `cargo add` / Maven |
| 配置 | 手工写代码 | 厂商配置工具 | **图形化工具一键导出 ENI / DENI + 多语言示例自动生成** |
| 文档 | 社区 / 源码 | 厂商手册 | **6 语言一致 SDK 在线文档 + 示例** |
| **— 高可靠 —** | | | |
| 实时抖动 | 视用户 RT 系统 | 硬件保障 | **配 DarraRT ≤ 1 µs** (Windows / Linux PREEMPT_RT) |
| 冗余 | 用户自实现 | 视厂商 | **零丢帧切换 + 三级故障自愈** (L1 冗余 / L2 降级 / L3 热插拔) |
| 功能安全 | — | 视厂商 | **FSoE (SIL3)** 协议栈 |
| 诊断 | 基础 | 视厂商 | **ETG.1510 在线诊断 + EMCY 历史 + 实时抖动统计** |

## Why Darra

Built around three goals: **feature-complete · easy to use · highly reliable**.

|  | SOEM (Open-source) | Dedicated master card | **Darra EtherCAT** |
|---|---|---|---|
| **— Feature-complete —** | | | |
| Mailbox | CoE / EoE / FoE | Vendor-dependent | **All 7**: CoE · EoE · FoE · SoE · AoE · VoE · **FSoE (SIL3)** |
| Advanced | DC, redundancy DIY | Vendor-dependent | **DC + Hot-Connect + Mailbox Gateway (ETG.8200) + CiA402 FSM** |
| Topology | Line / tree | Vendor-dependent | **Line / tree / ring / branch / star + hot-plug** |
| **— Easy to use —** | | | |
| Languages | C only | Vendor-specific SDK | **6 byte-consistent** (C / C++ / C# / Java / Python / Rust) |
| Install | Build & integrate yourself | Hardware + vendor IDE | **One-line via package manager**: `dotnet add` / `pip install` / `cargo add` / Maven |
| Config | Hand-coded | Vendor config tool | **GUI tool exports ENI / DENI + multi-language example auto-generation** |
| Docs | Community / source | Vendor manual | **Unified online SDK docs + examples for 6 languages** |
| **— High reliability —** | | | |
| RT jitter | Depends on user RT stack | Hardware-guaranteed | **≤ 1 µs with DarraRT** (Windows / Linux PREEMPT_RT) |
| Redundancy | User-implemented | Vendor-dependent | **Zero frame loss + 3-level recovery** (L1 redundancy / L2 degrade / L3 hot-plug) |
| Safety | — | Vendor-dependent | **FSoE (SIL3)** protocol stack |
| Diagnostics | Basic | Vendor-dependent | **ETG.1510 live diagnostics + EMCY history + jitter stats** |

---
## 核心能力 · Key capabilities

### 初始化 · Initialization

三种方式按场景选用. *Three init paths to fit common scenarios.*

- 🟢 **DENI 文件 / DENI file** (★ 生产推荐 / Recommended) — Darra 配置工具一键导出 ESI/PDO/DC/启动参数, 1 行加载. *Exported by the Darra GUI tool with all ESI / PDO / DC / startup preset; load in one line.*
- 🟡 **ESI 目录 + 自动配 / ESI dir + auto-config** — 给 ESI 库, SDK 按从站身份自动套默认参数. *Pass an ESI library; the SDK auto-applies defaults per slave identity.*
- 🟠 **纯自动配 / Pure auto-config** — 无 ESI 也可, 用从站 CoE 对象字典自动配 (调试 / 演示场景). *Works without ESI by reading the slave's own CoE object dictionary (debug / demo).*

### 协议与可靠性 · Protocols & reliability

- **全 7 邮箱协议 / All 7 mailbox protocols** — CoE · EoE · FoE · SoE · AoE · VoE · **FSoE (SIL3)**.
- **DC 分布式时钟 / Distributed Clocks** — ≤ 1 µs 同步, 静态 + 动态偏移补偿 (配 DarraRT). *Sub-µs sync with static + dynamic offset compensation (with DarraRT).*
- **冗余 + Hot-Connect / Redundancy + Hot-Connect** — 双链路单周期切换, 环 / 分支拓扑, 零丢帧. *Single-cycle dual-link failover, ring / branch topology, zero frame loss.*
- **三级故障自愈 / 3-level recovery** — L1 冗余切换 · L2 通信降级 · L3 热插拔身份验证 + CoE 重入 PreOP. *L1 redundancy / L2 degrade / L3 hot-plug identity verification + CoE re-enter PreOP.*
- **诊断 / Diagnostics (ETG.1510)** — 32-bit CRC + 断线定位 + AL Status 解析 + 紧急消息历史 + 实时抖动统计. *32-bit CRC + link-loss locating + AL Status parsing + EMCY history + live jitter stats.*

### 高级 API · High-level APIs

- **一步初始化 / One-step init** `EcInit` — 把 Initialize + SetNetwork + LoadConfig + SetStateSequence + Start 五步一行解决. *Collapses 5 steps into a single call.*
- **状态链 / State chain** `SetState(OP)` — 自动 INIT → PreOp → SafeOp → OP, 失败回退诊断. *Auto INIT → PreOp → SafeOp → OP with failure diagnostics.*
- **启动参数管线 / Startup parameter pipeline** — 批量添加 SDO 启动参数, 状态切换时一次写入. *Batch SDO startup parameters, applied on state transition.*
- **CiA402 驱动状态机 / CiA402 drive FSM** — 一行使能 / 故障复位, 自动解析驱动状态字. *One-line enable / fault-reset; auto-parses the drive statusword (Switch on / Operation enabled / Fault).*
- **PDO 类型化读写 / Typed PDO I/O** — 按 U16 / I32 / F32 / 结构体直接读写, 自动字节序处理. *Read / write by U16 / I32 / F32 / structs with automatic endianness.*
- **邮箱网关 / Mailbox Gateway** — `ETG.8200` 透传, 兼容 TwinCAT / 第三方工具远程访问 SDO. *ETG.8200 pass-through compatible with TwinCAT and 3rd-party SDO tools.*
- **拓扑查询 / Topology query** — 实时构建从站网络拓扑树, 含分支 / 环识别. *Real-time slave network tree with branch / ring detection.*
---

## Install

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

```bash
cargo add darra-ethercat-master
```

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

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

---

## 快捷使用 · Quick start

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

```rust
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 / 邮箱网关 / 诊断**.

```rust
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](https://crates.io/crates/darra-ethercat-master) |
| **C#** | `Darra.EtherCAT.Master` | [NuGet](https://www.nuget.org/packages/Darra.EtherCAT.Master/) |
| **Python** | `darra-ethercat-master` | [PyPI](https://pypi.org/project/darra-ethercat-master/) |
| **Java** | `xyz.darra:darra-ethercat-master` | [Maven Central](https://central.sonatype.com/artifact/xyz.darra/darra-ethercat-master) |
| **C / C++** | `darra-ethercat-c` / `darra-ethercat-cpp` | [Releases](https://ethercat.darra.xyz/release/) |

---

## 文档 · 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 驱动说明](https://ethercat.darra.xyz/docs/driver).
>
> *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.*

---
