<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 主站协议栈的 Rust SDK：全部 7 种邮箱协议 + CiA 402/401 驱动配置 + DC 分布式时钟 + 电缆冗余 + 复杂拓扑，配 DarraRT 实时内核驱动可达微秒级帧时序。6 种语言 SDK 行为字节级一致。

*Rust SDK for the Darra EtherCAT master stack — all 7 mailbox protocols, CiA 402/401, distributed clocks, cable redundancy and complex topologies; microsecond-level frame timing with the DarraRT real-time driver.*

---

## 性能 · Performance

帧发送周期抖动实测（配 DarraRT 实时内核驱动）：

| 平台 / Platform | 建议周期 / Cycle | 帧抖动(平均) / Jitter | 最大抖动 / Max |
|---|---|---|---|
| Windows 10 IoT (SMI 抑制) | 62.5 µs | 1.0 µs | 4.2 µs |
| Linux PREEMPT_RT | 62.5 µs | 0.7 µs | 3.2 µs |
| FreeRTOS | 31.25 µs | 0.3 µs | 2 µs |

- 最小周期 **31.25 µs** · DC 同步 **≤ 1 µs** · 零拷贝 PDO 映射
- DENI 文件加载比从零扫描快约 **50%**（实测 7.4 s vs 15.2 s）

> 微秒级实时由 SDK + DarraRT 实时内核驱动 + 兼容硬件共同提供。SMI/SMM 属硬件层中断，完全抑制需 BIOS/UEFI 配合。
> *Microsecond timing is delivered by the SDK together with the DarraRT real-time driver and supported hardware; full SMI suppression requires BIOS/UEFI tuning.*

---

## 能力 · Capabilities

- **全邮箱协议** — CoE (SDO/PDO/EMCY/CiA402) · SoE · FoE · EoE · AoE · VoE · FSoE（功能安全 SIL3）
- **驱动配置** — CiA 402 全模式 (CSP/CSV/CST/PP/PV/HM) + CiA 401 数字/模拟 I/O
- **可靠性** — 电缆冗余零丢帧切换 · 三级故障自愈（不停 PDO 循环）· 运行中热插拔
- **复杂拓扑** — 线 / 星 (EK1122) / 树 (EK1100) / 环 / 混合
- **在线诊断** — 从站状态 / AL Status Code / PDO 值实时可读 · 周期抖动统计 (ETG.1510)
- **邮箱网关** — ETG.8200，兼容 TwinCAT 等第三方工具
- **6 语言一致** — C / C++ / C# / Java / Python / Rust，枚举 / 错误码 / CRC 字节级一致

---

## 安装 · 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 实时内核驱动（随安装包，首次以管理员运行）。
> *Requires Rust 1.70+, Windows 10/11 x64, and the DarraRT real-time kernel driver (bundled in the installer).*

---

## 示例 · Example

DENI 一行加载 → 进 OP → PDO / 邮箱读写：

```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(EcState::Operational)?;        // 自动 INIT → PreOp → SafeOp → OP

    let slave = master.slave(1);

    // 过程数据 (PDO)：进 OP 后内核每周期自动收发，循环里直接访问最新值
    let statusword: u16 = slave.pdo_read_input_u16(0);   // 读输入 (TxPDO)
    slave.pdo_write_output_i32(0, 100_000)?;             // 写输出 (RxPDO)，下一周期自动发出

    // 非周期邮箱 (CoE SDO)
    let data = slave.coe().sdo_read(0x6041, 0x00, false)?;   // 类型化读
    let sw = u16::from_le_bytes([data[0], data[1]]);

    Ok(())
}
```

---

## 版本兼容 · Version compatibility

| 升级 / Upgrade | 重装驱动? / Reinstall driver? |
|---|---|
| PATCH (X.Y.1 → X.Y.2) | ❌ `cargo update` 即可 |
| MINOR / MAJOR | ✅ 需同步更新配套驱动安装包 |

`master.build()` 启动时自动校验 SDK 与驱动版本，不匹配写日志 Warning。

---

## 更多 · More

- **Rust SDK 文档 / Docs** — <https://ethercat.darra.xyz/docs/sdk/rust>
- **官网 / Homepage** — <https://ethercat.darra.xyz>
- **应用案例 / Examples** — <https://ethercat.darra.xyz/docs/examples>
