# Darra EtherCAT Master · C# 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 | **一行 `dotnet add package`** |
| 文档 / Docs | 散乱 PDF | **完善的在线 SDK 文档** |

---

## 核心能力 · Key capabilities

**初始化** — 三种方式按场景选:
- 🟢 **DENI 文件** (★ 推荐) — Darra 配置工具一键导出, ESI/PDO/DC/启动参数全套预置.
- 🟡 **ESI 目录 + 自动配** — `SetEsiFiles + EnableAutoStartup`, SDK 按从站身份自动套默认参数.
- 🟠 **纯自动配** — 没 ESI 也行, 用从站自带 CoE 对象字典自动配 (调试 / 演示场景).

**协议覆盖** — CoE · EoE · FoE · SoE · AoE · VoE · **FSoE (SIL3)**

**核心特性** — DC 分布式时钟 (≤1 µs) · Hot-Connect + 冗余 (单周期切换) · CiA402 驱动状态机 · 紧急消息 (EMCY) 历史 · PDO 类型化读写

**网络服务** — 邮箱网关 (ETG.8200, TwinCAT/第三方工具透传) · 诊断系统 (ETG.1510, 帧率 / 错误率 / AL Status / 拓扑查询)

---

## Install

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

或在 `.csproj`:

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

> **要求**: Windows 10/11 x64 · .NET Framework 4.6.1+ / .NET 6/7/8/9 · 首次运行需以管理员安装 DarraRT 实时内核驱动 (SDK 强制依赖, 兼容硬件).

---

## 快捷使用 · Quick start

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

```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));
```

---

## 高级使用 · Advanced

**自动搜网卡 + ESI 自动配** · **异步邮箱写 (支持取消)** · **CiA402 / 邮箱网关 / 诊断**.

```csharp
using System.Linq;
using System.Threading;
using DarraEtherCAT_Master;

// ① 自动搜网卡 (取有从站的那张 NIC)
var nets = DarraEtherCAT.GetNetworkInfo(needSlavesNum: true);
var ec = nets.FirstOrDefault(n => n.SlaveNum > 0)
         ?? throw new Exception("未发现 EtherCAT 网络");

// ② ESI 目录 + 自动配 (无 DENI 场景)
using var master = new DarraEtherCAT()
    .SetEsiFiles(@"C:\Esi")             // ESI 目录, SDK 按身份自动套默认参数
    .SetNetwork(ec.Name)
    .EnableAutoStartup()
    .Build()
    .Master;

master.SetState(EcState.OP, out _);

// ③ 异步邮箱写 (支持 CancellationToken, 不阻塞 UI 线程)
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));
bool ok = await master.Slaves[0].CoE.SDOWriteAsync(
    index: 0x607A, subindex: 0x00,
    data: BitConverter.GetBytes(100_000),
    cancellationToken: cts.Token);

// ④ CiA402 驱动一步使能 (Switch on → Operation enabled)
master.Slaves[0].CoE.CiA402?.Enable();

// ⑤ 诊断消息订阅 (Emergency Recorder, ETG.1510)
master.Slaves[0].CoE.DiagnosticMessageReceived += (_, e) =>
    Console.WriteLine($"诊断消息 0x{e.DiagCode:X8}");

// ⑥ 诊断快照 (帧率 / 错误率)
var diag = master.Diagnostics.GetSnapshot();
Console.WriteLine($"频率 {diag.Frequency} Hz, 错误 {diag.ErrorCount}");

// ⑦ 邮箱网关 (TwinCAT / 第三方工具远程透传 SDO, ETG.8200)
MailboxGateway.Start(masterIndex: 0, port: 8200);
```

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

---

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

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

| Language | Package | Registry |
|---|---|---|
| **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) |
| **Rust** | `darra-ethercat-master` | [crates.io](https://crates.io/crates/darra-ethercat-master) |
| **C / C++** | `darra-ethercat-c` / `darra-ethercat-cpp` | [Releases](https://ethercat.darra.xyz/release/) |

---

## 文档 · Documentation

- **官网 · Homepage**: <https://ethercat.darra.xyz>
- **C# SDK 文档**: <https://ethercat.darra.xyz/docs/sdk/csharp>
- **快速开始**: <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.*

---
