C/C++ SDK 概述

DarraEtherCAT C SDK 提供了用于开发 EtherCAT 主站应用程序的纯 C 原生接口，直接封装 Darra.Core.dll，支持主站与从站之间的高速实时通信。

安装

C SDK 提供两种使用方式:

方式一：动态加载（推荐） — 定义 DYNAMIC_LOAD 宏，运行时通过 LOAD_DLL() 加载 DLL，所有函数通过 dll_t 结构体中的函数指针调用。无需链接 .lib 文件。

#define DYNAMIC_LOAD
#include "ethercat.h"

int main(void) {
    dll_t dll;
    if (!LOAD_DLL(&dll, "Darra.Core.dll")) return 1;

    uint16_t master = dll.Initialize();
    /* ... 通过 dll.FuncName() 调用所有函数 ... */
    dll.Dispose(master);
    UNLOAD_DLL(&dll);
    return 0;
}

方式二：静态链接 — 不定义 DYNAMIC_LOAD，直接声明函数原型，链接 Darra.Core.lib。

# MSVC 静态链接
cl /Fe:my_app.exe main.c Darra.Core.lib /I include

# MSVC 动态加载 (无需 .lib)
cl /Fe:my_app.exe main.c /I include /DDARRA_DYNAMIC_LOAD

# GCC/MinGW 动态加载
gcc main.c -I include -DDARRA_DYNAMIC_LOAD -o my_app.exe

系统要求

项目	要求
操作系统	Windows 7+（推荐 Windows 10/11）/ Linux
编译器	MSVC 2019+、GCC 7+、Clang 10+
标准	C11 或更高
网络适配器	常规以太网网卡
权限	管理员/root 权限

安装 DarraRT 驱动

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

优势：< 1us 抖动 · 最优 DC 同步 · 替代低端控制卡 · 无需专用硬件

快速开始

使用 Darra 配置工具

1. 打开 Darra 配置工具，扫描 EtherCAT 网络
2. 配置从站参数（PDO 映射、DC 设置等）
3. 导出 DENI 配置文件
4. 在代码中加载 DENI 文件初始化主站

#define DYNAMIC_LOAD
#include "ethercat.h"
#include <stdio.h>

int main(int argc, char* argv[]) {
    dll_t dll;
    if (!LOAD_DLL(&dll, "Darra.Core.dll")) return 1;

    /* 初始化 + 绑定网卡 */
    uint16_t master = dll.Initialize();
    if (master == 0) { UNLOAD_DLL(&dll); return 1; }

    uint16_t slave_count = dll.SetNetwork(master, argv[1], "");
    printf("发现 %d 个从站\n", slave_count);

    /* 链式状态转换到 OP */
    if (!dll.SetStateSequence(master, EC_STATE_OPERATIONAL, 10000)) {
        dll.Dispose(master); UNLOAD_DLL(&dll); return 1;
    }
    dll.Start(master);

    /* 读写 IO */
    int32_t out_size = 0, in_size = 0;
    uint8_t *out_ptr = NULL, *in_ptr = NULL;
    dll.GetIO(master, 1, &out_size, &out_ptr, &in_size, &in_ptr);
    printf("从站1: 输出 %d 字节, 输入 %d 字节\n", out_size, in_size);

    getchar();

    dll.Stop(master);
    dll.Dispose(master);
    UNLOAD_DLL(&dll);
    return 0;
}

核心概念:

• 主站索引 (master_index) — uint16_t 标识主站实例。Initialize() 返回（>0 成功）
• dll_t 结构体 — 动态加载模式下包含所有 DLL 导出函数指针，通过 dll.FuncName() 调用
• 多实例 — 每个主站实例管理一条独立的 EtherCAT 总线，使用不同的网卡，CPU 核心可独立分配

高级 API

SDK 提供了一组高级 API，简化常见操作流程。ethercat_advanced.h 头文件提供更多便捷封装：

功能	API 函数 / 头文件	说明
一步初始化	EcInit / EcInitFromFile / EcClose	JSON 配置一步完成主站初始化
状态链转换	SetStateSequence	自动执行多步状态转换链
启动参数管线	AddStartupParameter / ApplyStartupParameters	批量添加启动参数并一次性应用
CiA 402 驱动状态机	CiA402_Enable / CiA402_SetMode	一步使能 / 故障复位 / 状态解析
EMCY 紧急消息缓冲	EmcyGetCount / EmcyGetHistory	读取从站紧急消息历史
PDO 类型化读写	PDOReadInputU16 / PDOWriteOutputI32 等	按类型直接读写 PDO 数据
拓扑查询	TopologyBuild / TopologyGetRoots / TopologyGetChildren	构建并查询从站网络拓扑树
OD 树遍历	od_load()	加载完整对象字典树
MDP 模块发现	mdp_discover()	模块化设备扫描
FSoE 管理器	fsoe_manager_create()	多连接管理
EoE Ping	eoe_ping()	ICMP Ping
PDO 变化监视器	pdo_monitor_create()	输入数据变化检测

快速示例:

/* 一步使能伺服驱动器 */
dll.CiA402_Enable(master, 1);

/* 类型化 PDO 读写 */
uint16_t status = PDOReadInputU16(master, 1, 0);
PDOWriteOutputI32(master, 1, 2, 100000);

/* 读取紧急消息 */
int n;
ec_emcy_t* hist = dll.EmcyGetHistory(master, 1, &n);

/* 拓扑查询 */
uint16_t children[64];
int cn = dll.TopologyGetChildren(master, 1, children, 64);