跳到主要内容

C# SDK 概述

DarraEtherCAT C# SDK 提供了用于开发 EtherCAT 主站应用程序的类库，支持主站与从站之间的高速实时通信。

当前版本

本文档对应 C# SDK v2.7.x。版本号可在运行时通过 DllVersionHelper.VersionNumber 查询，详见 DLL 版本信息。

安装​

Install-Package Darra.EtherCAT.Master

或使用 .NET CLI：

dotnet add package Darra.EtherCAT.Master

系统要求​

项目要求
操作系统Windows 7+ (推荐 Windows 10/11)
.NET.NET Standard 2.0 (兼容 .NET Framework 4.6.1+ / .NET 6+)
网络适配器常规以太网网卡
权限管理员权限

安装 DarraRT 驱动​

DarraRT 驱动提供微秒级实时性能，完全免费。详见 下载页面。

✅ 优势：< 1μs 抖动 · 最优 DC 同步 · 纯软件实时 · 无需专用硬件

快速开始​

使用 Darra 配置工具
  1. 打开 Darra 配置工具，扫描 EtherCAT 网络
  2. 配置从站参数（PDO 映射、DC 设置等）
  3. 导出 DENI 配置文件
  4. 在代码中加载 DENI 文件初始化主站
// ★ 推荐方式: 使用 DENI 文件 (Darra 配置工具一键导出)
var result = new DarraEtherCAT()
    .SetENI(@"C:\EtherCAT\MyProject.deni")
    .Build();

if (result.Success)
{
    var master = result.Master;
    master.SetState(EcState.OP);
    // 开始通信...
}

备选方式: 自动搜索网卡 (无 DENI 时)​

不使用 DENI 时, 用 GetNetworkInfo() 自动扫描所有网卡, 取有从站的那张, 不必硬编码 \Device\NPF_{GUID}:

// 扫所有 NIC 并探测从站数 (耗时 ~500ms-1.5s)
var networks = DarraEtherCAT.GetNetworkInfo(needSlavesNum: true);

// 选有从站的 NIC (一般只会有一张)
var ec = networks.FirstOrDefault(n => n.SlaveNum > 0);
if (ec == null)
{
    Console.WriteLine("未发现 EtherCAT 网络");
    return;
}
Console.WriteLine($"找到: {ec.Desc} (从站 {ec.SlaveNum} 台, MAC={ec.Mac})");

using var master = new DarraEtherCAT()
    .SetNetwork(ec.Name)
    .Build()
    .Master;

master.SetState(EcState.OP, out _);
何时用哪种
  • DENI — 生产环境, 一行加载 ESI/PDO/DC 全套参数, 推荐.
  • 自动搜索 — 演示 / 工具类应用 / 不需要预配置启动参数的场景.

高级 API​

SDK 提供了一组高级 API，简化常见操作流程：

功能说明
一步初始化 (EcInit)JSON 配置一步完成主站初始化，无需逐步调用
状态链转换 (SetState)自动执行多步状态转换链
启动参数管线 (AddStartupParameter/Apply)批量添加启动参数并一次性应用
CiA 402 驱动状态机一步使能/故障复位/状态解析
EMCY 紧急消息缓冲读取从站紧急消息历史记录
PDO 类型化读写按类型直接读写 PDO 数据（U16/I32/F32 等）
拓扑查询构建并查询从站网络拓扑树

快速示例:

// 一步使能伺服驱动器 (CiA 402 通过 slave.CoE.CiA402 访问)
slave.CoE.CiA402.Enable();

// 类型化 PDO 读写
var input = slave.PDO.InputsMapping<ServoInput>();
var output = slave.PDO.OutputsMapping<ServoOutput>();

// 读取紧急消息
var emcyList = slave.CoE.GetEmergencyHistory();

// 拓扑查询
var children = slave.Children;

C# 特有语法糖​

除标准 API 外, C# SDK 在 Master.Sugar 命名空间提供一组利用 .NET 语言特性的可选扩展, 让代码更简洁优雅. 详见 C# 特有语法糖 — 包含 Deconstruct 元组解构 / record struct 不可变身份 / Range 索引 / LINQ 筛选 / Span<byte> 零拷贝 PDO / IObservable<T> 事件流 / await foreach 诊断流 / async/await 状态切换. 这些是可选的, 不影响标准 API 使用.

自动健康检查 · Auto health checks​

master.Build() 时自动跑, 不匹配 → SDK 日志 Warning:

  • 驱动版本比对 — SDK 自动查询实时驱动的内核版本, 跟 SDK 自身 MAJOR.MINOR 比对, 不匹配时给出警告
  • RT 核隔离 — SDK 后台检查 CPU 核心隔离配置是否就位, 缺失时提示重装 SDK

错误码本地化 · Error localization​

AL Status 描述双语. SDK 默认英文, 中文专用接口给 UI:

string en = ((EcALState)code).GetDescription();         // English (default)
string zh = ((EcALState)code).GetDescriptionChinese();  // 中文 (UI 显示)
var drv = DriverVersionHelper.Get();                   // 内核驱动版本

版本兼容​

  • 同 MAJOR.MINOR 内 PATCH 互相兼容 (例 2.7.0 ↔ 2.7.2), 包管理器升级即可, 不需重装驱动
  • MAJOR / MINOR 变化 → 必须重装配套的驱动安装包, 否则会报版本兼容错误