跳到主要内容

C# SDK 概述

开发 EtherCAT 主站应用的 .NET 类库。

当前版本

本文档对应 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 Standard 2.0 (兼容 .NET Framework 4.6.1+ / .NET 6+)
  • 权限: 管理员
  • 实时内核驱动: 随安装包提供, 微秒级实时、无需专用硬件, 见 Windows 驱动

快速开始​

使用 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​

功能说明
一步初始化 (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# 特有语法糖​

Master.Sugar 命名空间提供一组可选的 .NET 扩展 (不用不影响标准 API): Deconstruct 元组解构 / record struct 不可变身份 / Range 索引 / LINQ 筛选 / Span<byte> 零拷贝 PDO / IObservable<T> 事件流 / await foreach 诊断流 / async/await 状态切换。详见 C# 特有语法糖。

自动健康检查​

master.Build() 启动时自动校验驱动版本与 RT 核隔离, 不匹配写 Warning。

错误码本地化​

AL Status 描述支持双语, 默认英文:

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

版本兼容​

当前 C# SDK v2.7.x。PATCH 兼容、MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。