C++ SDK 概述

Header-Only C++17 封装库， 主命名空间 darra::（darra::ethercat 提供同名别名，可混用）。RAII 生命周期、移动语义、std::function 回调、std::optional 返回、异常处理。

当前版本 2.11.0

本文档对应 SDK 2.11.0。2.5.x 的 MDP 进 OP 自动编排、per-group WKC 访问器、从站邮箱健康度可观测等能力保留， 各章节标注"2.5.x 新增 / 接口变更"。

C++ 层提供的封装

特性	C++ SDK
资源管理	RAII 析构自动释放
类型安全	强类型类
回调机制	std::function + Lambda
错误处理	异常 (DarraException)
字符串	std::string 自动管理
数据容器	std::vector / std::optional
从站访问	master.GetSlave(1).GetCoE().SDORead(...)
拷贝语义	禁止拷贝， 仅支持移动

#include "ethercat.hpp"
using namespace darra::ethercat;

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

    master.Events().SetPDOCallbackSync([&](uint16_t mi) {
        std::vector<uint8_t> inFrame;
        darra::SlavePDO::CopyInputFrame(dll, master.MasterNumber(), 1, inFrame);
    });

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

热路径用 InputsMapping / OutputsMapping 映射一次钉页；CopyInputFrame 是整帧快照，不是 0 拷贝。

安装

从 下载页面 获取 SDK 包 (含头文件与运行时库)。

#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 10/11 x64（本包 win-x64 只含 Windows 二进制）
编译器	MSVC 2019+（头文件 #pragma comment 自动链 darra_ethercat.lib）；GCC / Clang 可编头文件， 需手动链接导入库
C++ 标准	C++17 或更高
权限	管理员

需安装实时内核驱动 (随安装包， 见 Windows 驱动)。

快速开始

使用 Darra 配置工具

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

#include <iostream>
#include "ethercat.hpp"

int main() {
    // ★ 推荐方式: 使用 DENI 文件 (Darra 配置工具导出)
    darra::dll_t dll;
    darra::EtherCATMaster master(dll);          // 构造需传 dll_t&
    master.SetENI("C:\\EtherCAT\\MyProject.deni")
          .Build();                              // SetENI 后必须 Build()
    master.SetState(darra::EcState::OP);

    auto& slave = master.GetSlave(1);
    auto data = slave.GetCoE().SDORead(0x6041, 0x00);   // GetCoE(), 不是 coe()
    if (data.size() >= 2) {
        uint16_t status = data[0] | (data[1] << 8);
        std::cout << "Statusword=0x" << std::hex << status << "\n";
    }
    return 0;  // RAII 自动析构
}

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

不使用 DENI 时， 用 GetNetworkInfo() 自动扫描所有网卡， 取有从站的那张：

#include <iostream>
#include <algorithm>
#include "ethercat.hpp"

int main() {
    dll_t dll;
    // 扫所有 NIC 并探测从站数 (耗时 ~500ms-1.5s)
    auto nets = darra::ethercat::GetAvailableNetworks(dll, /*isRedundant=*/false,
                                                      /*needSlaveCount=*/true);

    // 选有从站的 NIC (AvailableNetworkInfo.slaveCount)
    auto it = std::find_if(nets.begin(), nets.end(),
                           [](const auto& n){ return n.slaveCount > 0; });
    if (it == nets.end()) {
        std::cerr << "未发现 EtherCAT 网络\n";
        return -1;
    }
    std::cout << "找到: " << it->desc << " (从站 " << it->slaveCount << " 台)\n";

    darra::EtherCATMaster master(dll);
    master.SetNetwork(it->name);
    master.Build();
    master.SetState(darra::EcState::OP);
    return 0;
}

何时用哪种

• DENI — 生产环境， 一行加载 ESI/PDO/DC 全套参数， 推荐。
• 自动搜索 — 演示 / 工具类应用 / 不需要预配置启动参数的场景。

功能概览

功能	C++ 类	说明
主站管理	EtherCATMaster	Builder 模式初始化、状态机、配置、RAII 生命周期
从站访问	Slave	80+ PascalCase 属性方法、状态、看门狗
PDO 读写	SlavePDO	进 OP 后 InputsMapping / OutputsMapping 映射一次钉在过程映像（读字段即当前值）；CopyInputFrame / WriteOutputFrame 是整帧快照
CoE	CoE	SDORead / SDOWrite 及类型化版本
CiA 401	CiA401	通用 I/O 协议
CiA 402	CiA402	伺服驱动器协议， Enable / Disable / FaultReset
SoE	SoE	SERCOS 参数读写及类型化版本
FoE	FoE	文件传输 (Download / Upload)
EoE	EoE	以太网隧道 (IP / MAC 配置、帧收发)
AoE	AoE	ADS 协议 (ReadWrite / SendCommand)
VoE	VoE	厂商协议 (Send / Receive / SendAndReceive)
FSoE	FSoE	功能安全 (Initialize / ReadSafeInput / WriteSafeOutput)
MDP	MDP	模块化设备配置， 进 OP 自动编排 (ETG.5001)
诊断	Diagnostics / MasterDiagnosticsInfo	通信统计、PDO 丢帧、CycleCount、WDK 绑核
配置	MasterConfig	周期时间、看门狗、VLAN、帧优先级等
邮箱网关	MailboxGatewayService	ETG.8200 UDP 邮箱网关（公开用户 API）

核心设计理念

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 核心

C++ 特有语法糖

除标准 API 外， C++ SDK 在 darra::sugar 命名空间提供一组利用 C++ 语言特性的可选扩展。 包含 <sugar/sugar.hpp> 一行引入全部。 详见 C++ 特有语法糖 — 包含 ScopedStart/State/LockIO RAII 守护 / SlavesView STL 友好迭代 / sugar::slave_opt(master, i) 返回 std::optional<std::reference_wrapper<Slave>> / master[1] operator overload / auto [vendor, product, rev] = darra::sugar::identity_tuple(slave) structured binding / std::string_view 零拷贝字符串参数 / StartAsync/StopAsync std::future 异步 / C++20 concepts (条件编译). 这些是可选的， 不影响标准 API 使用。

错误码描述

AL Status / SDO / SoE 错误码描述的语言取决于封装层：statics 的 al_status_description / sdo_error_description / soe_error_description 返回英文（AL Status 走 ETG.1020 内核默认英文表）；protocol_codes 的 sdo_abort_description / soe_error_description 返回中文（AL Status 中文描述另有 AL_StatusCode_GetDescriptionChinese）。FSoE 状态与错误码描述双语，后缀 _cn 为中文、_en 为英文；无后缀版本 FSoE 状态返回英文、FSoE 错误返回中文：

using namespace darra::ethercat::statics;

std::string en = al_status_description(code);            // AL Status (English)
const char* fs = fsoe_state_description_cn(st);          // FSoE 状态 (中文)
const char* fe = fsoe_error_description_en(err);         // FSoE 错误 (English)
auto drv = DriverVersionHelper::get(dll);                // 内核驱动版本 (需传 dll_t&)

版本兼容

当前 SDK 2.11.0。Core / 驱动 / GUI 同号升级；MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。