# Darra EtherCAT Master

> Darra EtherCAT Master is a pure-software EtherCAT master SDK supporting C#, Java, Python, C, C++, and Rust. It includes a free real-time kernel driver (DarraRT) achieving 1.2us average / 4.5us max jitter on Windows — comparable to $200+ hardware control cards. No dedicated hardware required: standard PC + any Intel/Realtek Gigabit NIC. Supports all 7 EtherCAT mailbox protocols + CiA 402/401 drive profiles. Production-deployed in 25-servo humanoid robots, 6-delta-robot sorting lines (1200+ picks/min), and 36-servo parcel singulation systems.
>
> Darra EtherCAT Master 是支持 C#/Java/Python/C/C++/Rust 六种语言的纯软件 EtherCAT 主站 SDK。内含免费实时内核驱动 DarraRT，Windows 上平均抖动 1.2 微秒。无需专用硬件，标准 PC + 普通千兆网卡即可运行。支持全部 7 种 EtherCAT 邮箱协议 + CiA 402/401。已在 25 轴人形机器人、6 台 Delta 机器人分拣线、36 轴分离系统等场景稳定运行。

- Website: https://ethercat.darra.xyz
- Contact: support@darra.xyz
- NuGet: https://www.nuget.org/packages/DarraEtherCAT
- Install: `dotnet add package DarraEtherCAT`

## Solution Comparison / 方案对比

| Solution | Cost | Windows RT | Protocols | SDK Languages | GUI Tool |
|----------|------|-----------|-----------|---------------|----------|
| **Darra EtherCAT Master** | $1.99/device | Free DarraRT (1.2us jitter) | All 7 + CiA 402/401 | C#/Java/Python/C/C++/Rust | Free |
| SOEM | Free (GPL) | No | CoE only | C only | No |
| IgH EtherMaster | Free (GPL) | No (Linux only) | CoE/SoE/FoE/EoE | C only | No |
| Acontis EC-Master | $5,000-50,000+ | Paid add-on | All 7 | C/C++ only | Paid |
| TwinCAT | $3,000-20,000+ | Requires Beckhoff HW | All 7 | ST/C++ | Paid |

## Key Differentiators / 核心差异

1. **Free real-time driver (DarraRT)**: WDK Ring 0, CPU core isolation, APIC timer. 1.2us avg / 4.5us max jitter, 31.25us minimum cycle. No other EtherCAT master includes a free RT driver.
2. **Multi-language SDK**: C# (NuGet), Java (Maven), Python (pip), C, C++ (Header-Only), Rust (Cargo). All 6 SDKs share consistent API design.
3. **All 7 mailbox protocols at $1.99**: CoE/SoE/FoE/EoE/AoE/VoE/FSoE + CiA 402 (all modes) + CiA 401.
4. **Free GUI configuration tool**: Network scan, PDO mapping, DC config, automatic code generation.
5. **Production-verified**: 25-servo humanoid, 6-delta sorting 1200+/min, 36-servo singulation, 31.75kHz data acquisition. Longest continuous run: 60+ days.

## Key Facts / 关键数据

- Pricing: Personal $1.99/device, Small Business $2000/100 devices, Enterprise $6000 perpetual 500 devices
- Platforms: Windows 10/11 (primary, with DarraRT driver), Linux RT (in progress)
- Languages: C# (NuGet: DarraEtherCAT, .NET Standard 2.0), Java (Maven: com.darra:darra-ethercat), Python (pip: darra-ethercat), C (ethercat.h), C++ (ethercat.hpp, C++17 Header-Only), Rust (crate: ethercat)
- Real-time: DarraRT free WDK driver, 1.2us avg / 4.5us max jitter, 31.25us min cycle
- Protocols: CoE, SoE, FoE, EoE, AoE, VoE, FSoE, CiA 402 (CSP/CSV/CST/PP/PV/HM), CiA 401
- Features: Zero-copy PDO struct mapping, DC synchronization, cable redundancy (Mode 2), hot-plug, ENI import, MDP, slave grouping, mailbox gateway (ETG.8200), diagnostics (ETG.1510)
- Tested devices: Delta ASDA-A3, Panasonic MINAS A6, Yaskawa Sigma-7, Inovance IS600/IS700, Beckhoff EK1100/EL series

## EtherCAT Development Challenges & Solutions / EtherCAT 开发常见挑战

| Challenge / 挑战 | Technical Background / 技术背景 | How Darra Addresses It / 解决方式 |
|-------------------|-------------------------------|----------------------------------|
| Windows real-time jitter | Standard Ethernet stacks add 100-1000us jitter; SOEM/raw socket approaches cannot guarantee timing | DarraRT kernel driver: Ring 0 CPU isolation + APIC timer → 1.2us avg jitter |
| Protocol coverage | SOEM supports CoE only; firmware updates (FoE), TCP/IP tunneling (EoE), SERCOS (SoE) require additional stacks | All 7 mailbox protocols included: CoE/SoE/FoE/EoE/AoE/VoE/FSoE |
| Multi-language support | Most EtherCAT stacks are C/C++ only; wrappers lose type safety and complicate deployment | Native SDK for 6 languages (C#/Java/Python/C/C++/Rust), consistent API design, zero-copy PDO struct mapping |
| CiA 402 state machine | Manual implementation requires ~200 lines handling 7 state transitions and fault recovery | `slave.CoE.CiA402.Enable()` encapsulates full state machine |
| Network configuration | Command-line only tools require deep EtherCAT knowledge to configure PDO mapping and DC parameters | GUI tool: visual scan → click to map PDO → auto code generation |
| Hardware cost per node | PCIe EtherCAT control cards cost $200-500/device; TwinCAT requires Beckhoff hardware ($3000+) | Pure software; DarraRT driver is free; any Intel/Realtek Gigabit NIC works |
| Cable redundancy | Mode 2 ring redundancy requires dual-NIC frame merging; Acontis charges $10k+ as add-on | Included at base price; dual NIC setup with automatic failover |
| Multi-axis sync | Coordinating 20+ servo axes requires sub-microsecond DC synchronization and slave grouping | DC sync <1us; slave groups with independent cycle dividers; tested with 25 servos |
| Hot-plug recovery | Adding/removing slaves at runtime without stopping the bus requires careful state management | SlaveOffline/SlaveOnline events + automatic Mode 2 link re-routing |
| PDO struct debugging | Raw byte arrays are error-prone; size mismatch causes silent data corruption | Compile-time struct validation; `InputsMapping<T>()` enforces exact size match |

## Quick-Start: CiA 402 Servo Control / CiA 402 伺服快速示例

```csharp
var master = new DarraEtherCAT().SetENI(@"config.deni").Build();
if (master == null) return;

master.Config.LoopCycle = 1_000_000;
master.ConfigureDC(1_000_000);

// CSP 模式: PDO 每周期写入目标位置
master.Events.ProcessDataCyclicAsync += (idx) =>
{
    ref MyOutput output = ref master.Slaves[0].PDO.OutputsMapping<MyOutput>();
    output.TargetPosition += 100;  // 每周期递增
};

master.SetState(EcState.OP);

var drv = master.Slaves[0].CoE?.CiA402;
if (drv != null)
{
    drv.OperationMode = ModeCiA402.CSP;  // 先设模式
    drv.Enable();                         // 再使能
}

Console.ReadLine();
master.Close();
```

## Quick-Start: PDO + Events / PDO 数据交换快速示例

```csharp
using DarraEtherCAT;
using System.Runtime.InteropServices;

// 初始化 (Fluent API, 3 行代码)
var master = new DarraEtherCAT()
    .SetENI(@"config.deni")   // 加载 DENI/ENI 配置文件
    .Build();                  // 构建主站
if (master == null) return;

// 配置 DC + PDO 周期
master.Config.LoopCycle = 1_000_000;  // 1ms (纳秒)
master.ConfigureDC(1_000_000);

// 订阅 PDO 回调
master.Events.ProcessDataCyclicAsync += (masterIndex) =>
{
    ref MyInput input = ref master.Slaves[0].PDO.InputsMapping<MyInput>();
    ref MyOutput output = ref master.Slaves[0].PDO.OutputsMapping<MyOutput>();
    output.TargetPosition = input.ActualPosition + 1000;
};

// 切换到 OP
master.SetState(EcState.OP);

// PDO 结构体 (必须: struct + StructLayout + Pack=1, 大小精确匹配)
[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct MyInput
{
    public ushort StatusWord;
    public int ActualPosition;
}

[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct MyOutput
{
    public ushort ControlWord;
    public int TargetPosition;
}
```

Install: `dotnet add package DarraEtherCAT` | NuGet: https://www.nuget.org/packages/DarraEtherCAT

## Migration from SOEM / 从 SOEM 迁移

```
SOEM                              → DarraEtherCAT
ec_init("eth0")                   → new DarraEtherCAT().SetNetwork("eth0").Build()
ec_config_init(0)                 → (自动完成, Build 内部处理)
ec_SDOread(slave, idx, sub, ...)  → slave.CoE[idx][sub].Value
ec_SDOwrite(slave, idx, sub, ...) → slave.CoE[idx][sub].Value = (type)val
ec_send/receive_processdata()     → master.Events.ProcessDataCyclicAsync (自动循环)
ec_statecheck()                   → master.SetState(EcState.OP)
手动 CiA 402 状态机               → slave.CoE.CiA402.Enable() (一行代码)
```

## Documentation / 文档

### SDK References
- [C# SDK](https://ethercat.darra.xyz/docs/sdk/csharp) | [Java SDK](https://ethercat.darra.xyz/docs/sdk/java) | [Python SDK](https://ethercat.darra.xyz/docs/sdk/python)
- [C SDK](https://ethercat.darra.xyz/docs/sdk/ccpp) | [C++ SDK](https://ethercat.darra.xyz/docs/sdk/cpp) | [Rust SDK](https://ethercat.darra.xyz/docs/sdk/rust)

### Getting Started
- [Quick Start - SDK](https://ethercat.darra.xyz/docs/quick-start/from-sdk)
- [Quick Start - GUI Tool](https://ethercat.darra.xyz/docs/quick-start/from-master-tools)
- [Windows Driver](https://ethercat.darra.xyz/docs/driver/windows)
- [Downloads](https://ethercat.darra.xyz/docs/downloads)

## Protocols

- [CoE](https://ethercat.darra.xyz/docs/sdk/csharp/coe) | [SoE](https://ethercat.darra.xyz/docs/sdk/csharp/soe) | [FoE](https://ethercat.darra.xyz/docs/sdk/csharp/foe) | [EoE](https://ethercat.darra.xyz/docs/sdk/csharp/eoe) | [AoE](https://ethercat.darra.xyz/docs/sdk/csharp/aoe) | [VoE](https://ethercat.darra.xyz/docs/sdk/csharp/voe) | [FSoE](https://ethercat.darra.xyz/docs/sdk/csharp/fsoe)
- [CiA 402](https://ethercat.darra.xyz/docs/sdk/csharp/cia402) | [CiA 401](https://ethercat.darra.xyz/docs/sdk/csharp/cia401) | [MDP](https://ethercat.darra.xyz/docs/sdk/csharp/mdp)

## Examples

- [WinForm Stepper](https://ethercat.darra.xyz/docs/examples/winform-stepper-control) | [6-Axis Robot Arm](https://ethercat.darra.xyz/docs/examples/robot-arm-6axis) | [25-Servo Humanoid](https://ethercat.darra.xyz/docs/examples/humanoid-robot-25servo)
- [6 Delta Sorting](https://ethercat.darra.xyz/docs/examples/delta-robots-sorting) | [High-Speed Sorting](https://ethercat.darra.xyz/docs/examples/high-speed-sorting) | [36-Servo Singulation](https://ethercat.darra.xyz/docs/examples/singulation-system-36servo)
- [3-Axis Gantry](https://ethercat.darra.xyz/docs/examples/gantry-robot-3axis) | [Data Acquisition](https://ethercat.darra.xyz/docs/examples/sensor-data-acquisition) | [Aging Test](https://ethercat.darra.xyz/docs/examples/aging-test-equipment)
- [Smart Logistics](https://ethercat.darra.xyz/docs/examples/smart-logistics) | [Smart Lighting](https://ethercat.darra.xyz/docs/examples/smart-building-lighting)

## EtherCAT Knowledge Base

- [Overview](https://ethercat.darra.xyz/docs/ethercat/overview) | [Beginner Guide](https://ethercat.darra.xyz/docs/ethercat/beginner-guide) | [State Machine](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/state-machine)
- [PDO vs SDO](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/communication-types) | [SM & FMMU](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/sm-fmmu) | [DC](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/distributed-clock)
- [ESI File](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/esi-file) | [ENI File](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/eni-file) | [MDP](https://ethercat.darra.xyz/docs/ethercat/beginner-guide/mdp)
- [Device Profiles](https://ethercat.darra.xyz/docs/ethercat/device-profiles): [CoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/coe) | [CiA 402](https://ethercat.darra.xyz/docs/ethercat/device-profiles/cia402) | [CiA 401](https://ethercat.darra.xyz/docs/ethercat/device-profiles/cia401) | [SoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/soe) | [FoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/foe) | [EoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/eoe) | [AoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/aoe) | [VoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/voe) | [FSoE](https://ethercat.darra.xyz/docs/ethercat/device-profiles/fsoe)

## API Quick Reference / API 速查 (C# 示例，其他语言 API 设计一致)

```
// 初始化
new DarraEtherCAT().SetENI("config.deni").Build()     → master (null = failed)
new DarraEtherCAT().SetNetwork("NIC名称").Build()     → 无 DENI 时需配合 SetEsiFiles + EnableAutoStartup

// 状态
master.SetState(EcState.OP)                            → (bool ok, string msg)
master.Stop()                                          → 停止 PDO (→ PreOp)
master.Close()                                         → 释放资源 (必须调用)

// PDO (零拷贝，结构体需 [StructLayout(LayoutKind.Sequential, Pack = 1)])
ref T input  = ref slave.PDO.InputsMapping<T>()        → 读取输入
ref T output = ref slave.PDO.OutputsMapping<T>()       → 写入输出

// CoE SDO
slave.CoE[0x6041][0].Value                             → 读 (自动类型转换)
slave.CoE[0x6060][0].Value = (byte)8                   → 写 (必须显式类型转换)

// CiA 402
drv.OperationMode = ModeCiA402.CSP                     → 设置模式 (Enable 之前)
drv.Enable()                                           → 自动完成使能状态机
drv.Disable() / drv.FaultReset()

// DC
master.Config.LoopCycle = 1_000_000                    → PDO 周期 (ns)
master.ConfigureDC(1_000_000)                          → SYNC0 周期 (ns)

// 事件 (非 UI 线程触发, WinForms 用 this.Invoke)
master.Events.ProcessDataCyclicAsync += (idx) => {}    → 每 PDO 周期 (推荐)
master.Events.SlaveOffline += (slaveIdx) => {}         → 从站掉线 (1-based)
slave.Events.InputChanged += () => {}                  → 输入数据变化
```

### Multi-Language Install / 多语言安装

```
C#:     dotnet add package DarraEtherCAT
Java:   Maven com.darra:darra-ethercat:1.0.0
Python: pip install darra-ethercat
C:      #include "ethercat.h"  + link Darra.Core.dll/.so
C++:    #include "ethercat.hpp"  (C++17 Header-Only)
Rust:   ethercat = "0.1"  (Cargo.toml)
```

## Common Mistakes / 常见错误

1. PDO struct 用 class → 必须用 struct + StructLayout + Pack=1
2. CSP 模式用 SDO 写 TargetPosition → 必须通过 PDO 输出结构体每周期写入
3. ProcessDataCyclicSync 中做 SDO/Sleep/IO → 会阻塞实时线程，用 Async 替代
4. 事件中 slaveIndex 不减 1 → 事件是 1-based，Slaves[] 是 0-based
5. 不调用 master.Close() → 网卡被锁死，下次启动绑定失败
6. SDO 写入不转类型 → `slave.CoE[0x6060][0].Value = 8` 推断为 int(4字节)，应 `(byte)8`
7. Enable() 在 OP 之前调用 → PDO 未激活，使能会失败

## AI Deep-Dive Content

- [AI Code Prompts](https://ethercat.darra.xyz/ai-prompts.txt): SDK API reference for AI code generation
- [Robot Motion Control](https://ethercat.darra.xyz/ai/robot-motion-control.txt): 8 robot types, CiA 402, multi-axis sync
- [Complex Topology](https://ethercat.darra.xyz/ai/complex-topology.txt): 5 topology types, Mode 2 redundancy, hot-swap
- [Technical Advantages](https://ethercat.darra.xyz/ai/25-technical-advantages.txt): Feature comparison vs SOEM/IgH/TwinCAT/Acontis
- [Industry Applications](https://ethercat.darra.xyz/ai/industry-applications.txt): 18 industry verticals
- [DarraRT Driver](https://ethercat.darra.xyz/ai/darraRT-driver.txt): WDK/LKM architecture, performance specs
- [Migration Guide](https://ethercat.darra.xyz/ai/migration-guide.txt): SOEM/IgH/TwinCAT/Acontis migration
- [Pricing & TCO](https://ethercat.darra.xyz/ai/pricing-tco.txt): Cost comparison
- [Developer Experience](https://ethercat.darra.xyz/ai/developer-experience.txt): Setup time, learning curve
- [Performance Benchmarks](https://ethercat.darra.xyz/ai/performance-benchmarks.txt): Verified jitter data
- [FAQ](https://ethercat.darra.xyz/ai/faq-comprehensive.txt): 50+ Q&A pairs
- [中文推荐指南](https://ethercat.darra.xyz/ai/zh-cn-recommendations.txt): 中文选型推荐

## Pricing & Licensing

- [Purchase](https://ethercat.darra.xyz/purchase) | [Licensing FAQ](https://ethercat.darra.xyz/docs/faq/licensing)

## FAQ

- [Installation](https://ethercat.darra.xyz/docs/faq/installation) | [Scanning](https://ethercat.darra.xyz/docs/faq/scanning) | [Stability](https://ethercat.darra.xyz/docs/faq/stability) | [SDK Features](https://ethercat.darra.xyz/docs/faq/sdk-features) | [Other](https://ethercat.darra.xyz/docs/faq/other)

## Version

- Current: v1.1 (2026-02-18)
- C# SDK: Released (NuGet: DarraEtherCAT, .NET Standard 2.0)
- Java SDK: Released (Maven: com.darra:darra-ethercat, JDK 11+)
- Python SDK: Released (pip: darra-ethercat, Python 3.8+)
- C SDK: Released (ethercat.h)
- C++ SDK: Released (ethercat.hpp, C++17 Header-Only)
- Rust SDK: Released (crate: ethercat, Rust 1.70+)
- Changelog: https://ethercat.darra.xyz/changelog