<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 · C# SDK

C# 语言的 EtherCAT 主站 SDK，覆盖全部 7 种邮箱协议、CiA 402 / CiA 401、分布式时钟 (DC)、电缆冗余与复杂拓扑，配 DarraRT 实时内核驱动达微秒级周期。

*EtherCAT master SDK for C#, covering all 7 mailbox protocols, CiA 402 / CiA 401, Distributed Clocks, cable redundancy and complex topologies; microsecond-level cycles 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

```powershell
dotnet add package Darra.EtherCAT.Master
```

或在 `.csproj`:

```xml
<PackageReference Include="Darra.EtherCAT.Master" Version="*" />
```

> 要求: .NET Framework 4.6.1+ / .NET 6/7/8/9 · Windows 10/11 x64 · 需 DarraRT 实时内核驱动（随安装包）。
> *Requires .NET Framework 4.6.1+ / .NET 6/7/8/9 · Windows 10/11 x64 · DarraRT real-time kernel driver (bundled with the installer).*

---

## 示例 · Example

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

```csharp
using DarraEtherCAT_Master;

using var master = new DarraEtherCAT()
    .SetENI(@"C:\EtherCAT\MyProject.deni")   // DENI 一行加载
    .Build()
    .Master;

master.SetState(EcState.OP, out _);          // 自动 INIT → PreOp → SafeOp → OP

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

//  ① 基本: byte[] + 手动解析
byte[] data = master.Slaves[0].CoE.SDORead(0x6041, 0x00);
ushort statusword = BitConverter.ToUInt16(data, 0);

//  ② 高级: 对象字典索引器 + 类型化 (一行)
ushort sw = master.Slaves[0].CoE[0x6041][0x00].GetValue<ushort>();

// 邮箱基本写: 字节版
master.Slaves[0].CoE.SDOWrite(0x607A, 0x00, BitConverter.GetBytes(100_000));
```

进 OP 后，过程数据 (PDO) 由内核每个总线周期自动实时收发，无需调"读/写"，循环里访问 `slave.PDO` 拿到的永远是最新一周期的输入，写出的输出会被下一周期自动 LRW 发出。

```csharp
var slave = master.Slaves[0];

// 读从站输入 PDO (TxPDO, 从站→主站) — 零拷贝 Span:
ReadOnlySpan<byte> inputs = slave.InputSpan();   // 长度 = slave.PDO.Inputs.Length

// 写从站输出 PDO (RxPDO, 主站→从站) — 直接写 IOmap, 下一周期自动发出:
Span<byte> outputs = slave.OutputSpan();
outputs[0] = 0xFF;
```

---

## 版本兼容 · Version compatibility

| 升级类型 / Upgrade | 需更新配套驱动? / Driver update? |
|---|---|
| **PATCH** (X.Y.1 → X.Y.2) | ❌ 不需要 / No |
| **MINOR / MAJOR** (X.Y.x → X.(Y+1).0 或 (X+1).0.0) | ✅ 需要 / Yes |

> `master.Build()` 启动自动校验 SDK 与驱动版本，不匹配时写 Warning。
> *`master.Build()` auto-checks SDK and driver versions at startup and logs a Warning on mismatch.*

---

## 更多 · More

- **C# SDK 文档 · Documentation**: <https://ethercat.darra.xyz/docs/sdk/csharp>
- **官网 · Homepage**: <https://ethercat.darra.xyz>
- **应用案例 · Examples**: <https://ethercat.darra.xyz/docs/examples>
