<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

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

`[ Windows · Linux · MCU ]`  `[ 6 语言 SDK / 6 languages ]`  `[ 全协议 / Full protocols ]`  `[ 高可靠 / Highly reliable ]`  `[ ethercat.darra.xyz ]`

---

## 为什么选 Darra

|  | SOEM 开源 | 专用主站板卡 | **Darra EtherCAT** |
|---|---|---|---|
| 协议覆盖 | 部分 | 视厂商 | **全协议 + 功能安全** |
| 拓扑 | 简单 | 视厂商 | **复杂拓扑 + 热插拔** |
| SDK 语言 | C 一种 | 厂商专用 | **6 语言一致** |
| 安装 | 自行集成 | 硬件 + IDE | **包管理器一行** |
| 配置 | 手工写代码 | 厂商工具 | **图形化一键导出** |
| 实时抖动 | 视 RT 系统 | 硬件保障 | **配 DarraRT ≤ 1 µs** |
| 可靠性 | 用户自实现 | 视厂商 | **冗余 + 故障自愈** |
| 诊断 | 基础 | 视厂商 | **完整在线诊断** |

## Why Darra

|  | SOEM (Open-source) | Dedicated master card | **Darra EtherCAT** |
|---|---|---|---|
| Protocols | Partial | Vendor-dependent | **Full + functional safety** |
| Topology | Simple | Vendor-dependent | **Complex + hot-plug** |
| Languages | C only | Vendor-specific | **6 byte-consistent languages** |
| Install | Build yourself | Hardware + IDE | **One line via package manager** |
| Config | Hand-coded | Vendor tool | **GUI one-click export** |
| RT jitter | Depends on RT stack | Hardware-guaranteed | **≤ 1 µs with DarraRT** |
| Reliability | DIY | Vendor-dependent | **Redundancy + auto-recovery** |
| Diagnostics | Basic | Vendor-dependent | **Full live diagnostics** |

---
## 版本兼容 · Version compatibility

- **同 MAJOR.MINOR 内 PATCH 任意升级互相兼容** (例 X.Y.1 ↔ X.Y.2 ↔ X.Y.3) — SDK 包管理器一行升级即可, **不需重装驱动**
- **MAJOR 或 MINOR 变化 → 必须重装驱动** — 驱动 .sys 内嵌了 Core.dll SHA256 白名单, 主/次版本变 → hash 变 → MS 必须重签 → 客户必须升级驱动
- `master.Build()` 自动比对 Core.dll ↔ 驱动版本, 不匹配 → 日志 Warning

| 升级类型 | 重装驱动? | 客户操作 |
|---|---|---|
| **PATCH** (X.Y.1 → X.Y.2) | ❌ 不需要 | `dotnet add package` / `pip install --upgrade` |
| **MINOR** (X.Y.x → X.(Y+1).0) | ✅ 必须 | 升级 SDK + 重装驱动安装包 (.msi) |
| **MAJOR** (X.Y.Z → (X+1).0.0) | ✅ 必须 | 同上 + 看 CHANGELOG (可能 API 变更) |

*PATCH within same MAJOR.MINOR is mutually compatible (e.g. X.Y.1 ↔ X.Y.2) — package manager upgrade only, no driver reinstall. MINOR or MAJOR change requires driver reinstall (Core.dll hash baked into kernel sys whitelist).*

## 启动性能 · Startup performance

- **DENI 加载比从零扫描快 50%** (实测 7.4s vs 15.2s)
- 推荐生产环境用 DENI 文件 (Darra 配置工具一键导出, 预存 ESI/PDO/DC/启动参数)
- 调试 / 演示场景用自动配 (无 DENI 也能跑, SDK 实时扫从站身份)

*DENI loading is 50% faster than full scan (7.4s vs 15.2s). Use DENI for production, auto-config for debugging.*

---
## 自动健康检查 · Auto health checks

`master.Build()` 时自动跑 (无需客户调用):

- **驱动版本比对 / Driver version match** — Core.dll 直读 `\\.\DarraRT` 拿内核驱动版本, 与 SDK 自身版本比 MAJOR.MINOR. 不匹配 → SDK 日志 Warning, 客户立刻看到 "需要升级驱动" 提示.
- **RT 核隔离配置 / RT core isolation** — 后台异步读 `HKLM\SOFTWARE\Darra\EtherCAT` marker. 缺失 (MSI 安装时未跑 CoreOptimize) → SDK 日志 Warning, 提示用户调 `EnsureRtIsolation(elevated:true)` 自动修复 (仅 C#, 跨语言 SDK 提示重装).

*Auto-runs on `master.Build()`: driver version match (Core.dll vs kernel) and RT core isolation registry check. Mismatches log warnings, no manual API call needed.*

## 错误码本地化 · Error code localization

AL Status Code 描述支持双语, 全部下沉到 Core.dll (VMP 保护):

| 接口 | 语言 | 用途 |
|---|---|---|
| `AL_StatusCode_GetDescription(code)` | English (默认) | 5 SDK 跨语言客户使用 |
| `AL_StatusCode_GetDescriptionChinese(code)` | 中文 | C# / Python 主界面 UI 使用 |
| `AL_StatusCode_GetRecoveryHint(code)` | English | 默认 |
| `AL_StatusCode_GetRecoveryHintChinese(code)` | 中文 | UI 显示 |

*AL Status descriptions are bilingual: English by default for SDKs, dedicated Chinese API for UI applications. All translations are baked into Core.dll with VMP protection.*

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

### 初始化 · Init

- 🟢 **DENI 文件 / DENI file** (★ 推荐 / Recommended) — 配置工具一键导出, 1 行加载. *One-click export, single-line load.*
- 🟡 **ESI 自动配 / Auto-config** — SDK 按从站身份自动套参数. *Auto-applies defaults per slave identity.*
- 🟠 **零配置 / Zero-config** — 无 ESI 用从站 CoE 字典自动配. *Reads slave's own object dictionary.*

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

- **全协议 / Full mailbox protocols** (含功能安全 SIL3 / incl. FSoE SIL3)
- **DC 同步 / Distributed Clocks** ≤ 1 µs (配 DarraRT)
- **冗余 + 故障自愈 / Redundancy + auto-recovery** — 零丢帧切换 / zero-loss failover
- **完整在线诊断 / Full live diagnostics**

### 高级 API · High-level APIs

- **一行初始化 / One-line init** — 5 步合 1. *5 steps in a single call.*
- **状态链 / State chain** — 自动 INIT → OP. *Auto walk to OP with diagnostics.*
- **CiA402 一行使能 / One-line drive enable**.
- **PDO 类型化读写 / Typed PDO I/O** — 自动字节序. *Automatic endianness.*
- **邮箱网关 / Mailbox gateway** — 兼容 TwinCAT 等第三方工具. *Compatible with TwinCAT and 3rd-party tools.*
---

## Install

从 <https://ethercat.darra.xyz/release/> 下载 zip,解压后:

```
darra-ethercat-c-<v>-win-x64/
├── include/darra_ethercat.h
├── lib/Darra.Core.lib
├── lib/Darra.Core.protocol.lib
├── lib/darra-ethercat-advanced.lib
├── bin/Darra.Core.dll
├── examples/
└── README.md
```

### Linux

```bash
gcc app.c -lDarraCore -o app
```

### Windows MSVC

```cmd
cl /I include app.c lib\Darra.Core.lib lib\Darra.Core.protocol.lib lib\darra-ethercat-advanced.lib
```

> **要求**: 任何 C99 编译器 · Windows 10/11 x64 · 首次运行需以管理员安装 DarraRT 实时内核驱动.

---

## 快捷使用 · Quick start

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

```c
#include <stdio.h>
#include <string.h>
#include <ethercat.h>

int main(void) {
    /* DENI 一步初始化 (Initialize + SetNetwork + LoadConfig + SetStateSequence + Start) */
    uint16_t m = EcInitFromFile("C:\\EtherCAT\\MyProject.deni");
    if (m == 0) return 1;
    /* DENI 路径已自动进 OP, 直接通信 */

    /* 邮箱读 — 两种风格任选: */
    int n = 0;
    char* sw = dx_sdo_read(m, 1, 0x6041, 0x00, FALSE, &n);

    /*  ① 基本: 位运算解析 */
    uint16_t statusword = (uint8_t)sw[0] | ((uint8_t)sw[1] << 8);

    /*  ② 高级: 类型化强转 (一行) */
    uint16_t sw_typed = *(uint16_t*)sw;

    if (sw) FreeMemory(sw);  /* dx_sdo_read 返回堆指针, 必须释放 */

    /* 邮箱基本写: 字节版 */
    int32_t target = 100000;
    dx_sdo_write(m, 1, 0x607A, 0x00, FALSE, (uint8_t*)&target, sizeof(target));

    EcClose(m);  /* 一步关闭: Stop + Dispose */
    return 0;
}
```

### OP 过程数据交互 (PDO I/O) · Process data in OP

进 OP 后, **过程数据 (PDO) 由内核每个总线周期自动实时收发**, 与 CoE (非周期邮箱) 不同: 不调"读/写", `GetIO` 直接拿到从站在 IOmap 中的输入/输出指针 (零拷贝), 读到的永远是最新一周期, 写出的会被下一周期自动 LRW 发出。

```c
/* 取从站 1 的 PDO 输入/输出指针 + 字节数 (零拷贝) */
int32_t out_size = 0, in_size = 0;
uint8_t *out_ptr = NULL, *in_ptr = NULL;
GetIO(m, 1, &out_size, &out_ptr, &in_size, &in_ptr);

/* 读输入 PDO (TxPDO, 从站→主站): 偏移 0 取一个 u16 */
uint16_t statusword = 0;
if (in_ptr && in_size >= 2) statusword = (uint16_t)(in_ptr[0] | (in_ptr[1] << 8));

/* 写输出 PDO (RxPDO, 主站→从站), 下一周期自动发出: */
if (out_ptr && out_size >= 1) out_ptr[0] = 0xFF;
```

---

## 高级使用 · Advanced

**自动搜网卡 + 链式状态转换 + 诊断**.

```c
#include <stdio.h>
#include <ethercat.h>

int main(void) {
    /* ① 自动搜网卡 (取有从站的那张 NIC) */
    int n = GetNetworkInfo(FALSE, TRUE);                          /* 扫描 + 探测从站数 */
    ec_networkInfo* nets = (ec_networkInfo*)GetNetworksPointer(); /* 内部指针, 无需释放 */

    uint16_t m = Initialize();
    int found = 0;
    for (int i = 0; i < n; i++) {
        if (nets[i].slaveNum > 0) {
            SetNetwork(m, nets[i].name, "");
            found = 1;
            break;
        }
    }
    if (!found) { Dispose(m); return 1; }

    /* ② 链式进 OP (自动 INIT → PreOp → SafeOp → OP, 10s 超时) */
    SetStateSequence(m, EC_STATE_OPERATIONAL, 10000);
    Start(m);

    /* ③ 通信 ... */

    Stop(m);
    Dispose(m);
    return 0;
}
```

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

---

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

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

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

---

## 文档 · Documentation

- **官网 · Homepage**: <https://ethercat.darra.xyz>
- **C SDK 文档**: <https://ethercat.darra.xyz/docs/sdk/ccpp>
- **快速开始**: <https://ethercat.darra.xyz/docs/quick-start>
- **协议详解**: <https://ethercat.darra.xyz/docs/ethercat>


> **⚠️ 关于"微秒级"实时性能 · 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.*

---
