跳到主要内容

C++ SDK 概述

DarraEtherCAT C++ SDK 是 Header-Only 的现代 C++17 封装库, 命名空间 darra::ethercat。提供 RAII 生命周期管理、移动语义、std::function 回调、std::optional 返回、异常处理, 支持主站与从站之间的高速实时通信。

与 C API 的对比​

特性C APIC++ SDK
资源管理手动 Dispose / CloseRAII 析构自动释放
类型安全void* 句柄强类型类
回调机制函数指针std::function + Lambda
错误处理返回值检查异常 (DarraException)
字符串char* + 手动释放std::string 自动管理
数据容器原始指针 + 长度std::vector / std::optional
从站访问API(handle, index, ...)master.GetSlave(1).GetCoE().SDORead(...)
拷贝语义无限制禁止拷贝, 仅支持移动
#include "ethercat.hpp"
using namespace darra::ethercat;

int main() {
    EtherCATMaster master(dll);
    master.SetNetwork("\\Device\\NPF_{...}");
    master.Build();
    master.SetState(EcState::OP);
    master.Start();

    master.Events().ProcessDataCyclicSync = [&](uint16_t mi) {
        auto& s = master.GetSlave(1);
        auto* input  = s.InputDataPointer();
        auto* output = s.OutputDataPointer();
    };

    // 离开作用域, 析构自动 Stop + Dispose
}

安装​

从 下载页面 获取 SDK 包, 包含 C++ 头文件与运行时库。

包含头文件:

#include "ethercat.hpp"

CMake 配置:

add_executable(my_app main.cpp)
target_compile_features(my_app PRIVATE cxx_std_17)
target_include_directories(my_app PRIVATE ${SDK_PATH}/include)

系统要求​

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

安装 DarraRT 驱动​

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

快速开始​

使用 Darra 配置工具
  1. 打开 Darra 配置工具, 扫描 EtherCAT 网络
  2. 配置从站参数 (PDO 映射、DC 设置等)
  3. 导出 DENI 配置文件
  4. 在代码中加载 DENI 文件初始化主站
#include "ethercat.hpp"
using namespace darra::ethercat;

int main() {
    try {
        EtherCATMaster master(dll);
        master.SetNetwork("\\Device\\NPF_{...}");
        master.SetEni("C:/EtherCAT/config.deni");
        if (!master.Build()) {
            printf("初始化失败\n");
            return -1;
        }

        master.Events().ProcessDataCyclicSync = [&](uint16_t mi) {
            auto& servo = master.GetSlave(1);
        };

        master.SetState(EcState::OP);
        master.Start();

        printf("运行中... 按 Enter 停止\n");
        getchar();
    } catch (const DarraException& e) {
        printf("错误: %s\n", e.what());
        return -1;
    }
    return 0;
}

功能概览​

功能C++ 类说明
主站管理EtherCATMasterBuilder 模式初始化、状态机、配置、RAII 生命周期
从站访问Slave80+ PascalCase 属性方法、状态、看门狗
PDO 读写SlavePDO零拷贝 PDO 数据指针访问
CoECoESDORead / SDOWrite 及类型化版本
CiA 401CiA401通用 I/O 协议
CiA 402CiA402伺服驱动器协议, Enable / Disable / FaultReset
SoESoESERCOS 参数读写及类型化版本
FoEFoE文件传输 (Download / Upload)
EoEEoE以太网隧道 (IP / MAC 配置、帧收发)
AoEAoEADS 协议 (ReadWrite / SendCommand)
VoEVoE厂商协议 (Send / Receive / SendAndReceive)
FSoEFSoE功能安全 (Initialize / ReadSafeInput / WriteSafeOutput)
MDPMDP模块化设备配置
诊断Diagnostics通信统计、PDO 丢帧、冗余状态
配置MasterConfig周期时间、看门狗、VLAN、帧优先级等

核心设计理念​

RAII 自动资源管理 — EtherCATMaster 在析构时自动调用 Stop() + Dispose(), 无需手动管理生命周期。

延迟初始化 — 从站协议子对象 (CoE / SoE / FoE 等) 采用延迟创建模式, 首次访问时才分配:

auto& s = master.GetSlave(1);
s.GetCoE();    // 首次调用, 创建 CoE 对象
s.GetCoE();    // 后续调用, 返回已缓存的对象

移动语义 — EtherCATMaster 支持移动但禁止拷贝, 确保资源唯一所有权:

EtherCATMaster master1(dll);
EtherCATMaster master2 = std::move(master1);
// master1 现在无效, master2 拥有资源

多实例支持 — 每个 EtherCATMaster 管理独立的 EtherCAT 总线, 使用不同网卡:

EtherCATMaster master1(dll);
master1.SetNetwork("adapter1");
master1.Build();

EtherCATMaster master2(dll);
master2.SetNetwork("adapter2");
master2.Build();
多实例要求
  • 每个实例必须使用不同的网卡 — 同一网卡不能被多个实例同时使用
  • CPU 核心自动分配 — 每个实例自动占用不同的 CPU 核心