跳到主要内容

Rust SDK 概述

用于开发 EtherCAT 主站应用的 crate，提供安全 Rust API 进行主站与从站的实时通信。

安装​

SDK 是商业私有库。先到 下载页面 取 darra-ethercat-master.crate，解压出源码目录：

tar -xzf darra-ethercat-master.crate     # 解出 darra-ethercat-master-2.11.0/

然后在 Cargo.toml 里写路径依赖，指到你解压出来的那个目录：

[dependencies]
darra-ethercat-master = { path = "../darra-ethercat-master-2.11.0" }

目录名带 crate 版本号，换版本时改这一行即可。

crate 名与库名
  • crate 名 (依赖声明): darra-ethercat-master
  • 库名 (代码中 use): darra_ethercat，例如 use darra_ethercat::EtherCATMaster;
包内容与运行期依赖

.crate 是源码包，内含 Cargo.toml、ffi/bindings.rs 与 README.md，不含 build.rs（Windows 链接不需要导入库 .lib）。发布目录另附 bin/Darra.Core.dll——运行期必须能找到它：复制到你的 exe 同目录，或放进 PATH。缺它进程起不来（Windows 退出码 0xC0000135）。请勿换成其它版本的 Darra.Core.dll，须与 SDK 版本配套。

环境要求​

项目要求
操作系统Windows 10/11（主交付）；Linux 尚未公开发布（SDK 与驱动未发布）
Rust1.70+ (stable)
权限管理员 (Windows) / root (Linux)
实时内核驱动随安装包提供，见 Windows 驱动

快速开始​

使用 Darra 配置工具
  1. 打开 Darra 配置工具，扫描 EtherCAT 网络
  2. 配置从站参数（PDO 映射、DC 设置等）
  3. 导出 JSON 配置文件
  4. 在代码中加载 JSON 文件初始化主站
use darra_ethercat::{EtherCATMaster, EcState};

fn main() -> darra_ethercat::Result<()> {
    // ★ 推荐方式: 使用 DENI 文件 (Darra 配置工具导出)
    // build() 返回 BuildResult (只实现 Deref, 无 DerefMut);
    // set_state 需要 &mut self, 故取出 .master 并 let mut
    let mut master = EtherCATMaster::builder()
        .set_eni(r"C:\EtherCAT\MyProject.deni")
        .build()?
        .master;

    master.set_state(EcState::Operational)?;

    // 读取从站数据 — 类型化 SDO 读取
    let slave = master.slave(1);
    let sw: u16 = slave.sdo_read_value(0x6041, 0x00)?;
    println!("Statusword=0x{:04X}", sw);

    Ok(())
}

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

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

use darra_ethercat::{EtherCATMaster, EcState};
use darra_ethercat::statics::network::enumerate_network_info;

fn main() -> darra_ethercat::Result<()> {
    // 扫所有 NIC 并探测从站数 (耗时 ~500ms-1.5s)
    let nets = enumerate_network_info(false, true);

    // 选有从站的 NIC
    let ec = nets.iter()
        .find(|n| n.slave_num > 0)
        .expect("未发现 EtherCAT 网络");
    println!("找到: {} (从站 {} 台)", ec.description, ec.slave_num);

    // build() 返回 BuildResult (只实现 Deref, 无 DerefMut);
    // set_state 需要 &mut self, 故取出 .master 并 let mut
    let mut master = EtherCATMaster::builder()
        .set_network(&ec.name, None)   // 第 2 参为 Option<&str> 冗余网卡
        .build()?
        .master;

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

设计理念​

  • RAII 自动释放 — EtherCATMaster 实现 Drop，超出作用域自动 Stop + Dispose
  • 工厂方法 — EtherCATMaster::new() / with_index() / from_json() / from_json_file()
  • Result 错误处理 — 可能失败的操作返回 Result<T, DarraError>
  • PDO 金路径：映射一次钉页 — SlavePdo::inputs_mapping / outputs_mapping 把 #[repr(C, packed)] 结构体钉在 live IOmap 上，同址直接读写；copy_slave_input_pdo / write_slave_output_pdo 是快照
  • 闭包回调 — 事件订阅使用 Rust 闭包，自动管理生命周期
  • 安全封装 — 默认 API 全为安全 Rust；0 拷贝映射（inputs_mapping / outputs_mapping）为 unsafe fn，裸指针解引用需自行 unsafe，见 PDO 输入输出

功能特性​

功能说明
一步初始化 (from_json/from_json_file)JSON 配置一步完成主站初始化
状态链转换 (set_state)自动执行多步状态转换链并应用启动参数
OD 树遍历 (OdList)加载完整对象字典，支持类型化读写
CiA 402 驱动状态机独立构造 CiA402Instance，PDO/SDO 自动切换
PDO 监控 (PdoMonitor)按字节范围监视 PDO 输入变化
FSoE 安全通信SafetyManager/SafeMdp 手动连接管理
拓扑查询构建并查询从站网络拓扑树
邮箱网关 (MailboxGateway)ETG.8200 UDP/TCP 邮箱网关，外部诊断工具入口

快速示例：

// 类型化 SDO 读写
let status: u16 = slave.sdo_read_value(0x6041, 0x00)?;
slave.sdo_write_value(0x6040, 0x00, &0x0006u16)?;

// OD 树遍历
let od = OdList::load(master.index(), 1)?;
for obj in &od.objects {
    println!("0x{:04X}: {}", obj.index, obj.name);
}

// CiA 402 独立构造
let pdo_map = Cia402PdoMap::scan(master.index(), 1)?;
let drv = CiA402Instance::new(master.index(), 1, pdo_map);
drv.enable_default()?;

// PDO 监控
let mut monitor = PdoMonitor::new(master.index());
monitor.watch(1, "statusword", 0, 2);
let changes = monitor.check();

// 拓扑查询
let topo = master.topology();
let children = master.topology_get_children(1);

Rust 特有语法糖​

darra_ethercat::sugar 模块提供利用 Rust 语言特性的可选扩展， use darra_ethercat::sugar::prelude::*; 一行解锁全部 (不影响标准 API)。包含 Indexable 索引 (master.indexable()[i])、SlaveIterExt 链式过滤 (by_state / by_group / by_vendor / with_dc)、mpsc::channel 状态变化通道、tokio::Stream 异步流 (feature async-tokio)、From/Into 转换、Display 枚举、try_slave(i)?。详见 Rust 特有语法糖。

错误码本地化​

AL Status 描述支持中英文， SDK 默认英文， 中文接口供 UI 调用：

use darra_ethercat::statics::{print::al_status_description, driver_version};

let en = al_status_description(code);     // English (默认)
let drv = driver_version::get();          // 内核驱动版本

版本兼容​

当前 SDK 版本 2.11.0（从 下载页面 取 crate）。PATCH 兼容、MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。