跳到主要内容

Rust SDK 概述

DarraEtherCAT Rust SDK 是用于开发 EtherCAT 主站应用程序的 crate，提供安全的 Rust API 进行主站与从站之间的高速实时通信。

安装​

在 Cargo.toml 中添加依赖：

[dependencies]
darra-ethercat-master = "2.7"

或使用 cargo add：

cargo add darra-ethercat-master
crate 名与库名
  • crate 名 (依赖声明 / cargo add): darra-ethercat-master
  • 库名 (代码中 use): darra_ethercat，例如 use darra_ethercat::EtherCATMaster;

系统要求​

项目要求
操作系统Windows 7+ (推荐 Windows 10/11) 或 Linux
Rust1.70+ (stable)
网络适配器常规以太网网卡
权限管理员权限（Windows）/ root 权限（Linux）

安装 DarraRT 驱动​

DarraRT 驱动提供微秒级实时性能，完全免费。

快速开始​

使用 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 全套参数, 推荐.
  • 自动搜索 — 演示 / 工具类应用 / 不需要预配置启动参数的场景.

设计理念​

Rust SDK 遵循 Rust 惯用模式：

  • RAII 自动释放 — EtherCATMaster 实现 Drop trait，超出作用域时自动 Stop + Dispose 释放资源
  • 工厂方法 — 通过 EtherCATMaster::new() / with_index() / from_json() / from_json_file() 创建主站
  • Result 错误处理 — 所有可能失败的操作返回 Result<T, DarraError>
  • 零拷贝 PDO — 通过 IOmap 指针直接访问过程数据
  • 闭包回调 — 事件订阅使用 Rust 闭包，自动管理生命周期
  • 安全封装 — 用户接触的全部 API 均为安全 Rust，无需 unsafe

功能特性​

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

快速示例:

// 类型化 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 特有语法糖​

除标准 API 外, Rust SDK 在 darra_ethercat::sugar 模块提供一组利用 Rust 语言特性的可选扩展. 用户 use darra_ethercat::sugar::prelude::*; 一行解锁全部. 详见 Rust 特有语法糖 — 包含 Indexable 索引 (master.indexable()[i]) / SlaveIterExt 链式过滤 (by_state / by_group / by_vendor / with_dc) / mpsc::channel 状态变化通道 / tokio::Stream 异步流 (feature async-tokio) / From/Into 跨类型转换 / Display 6 个枚举 / try_slave(i)? 错误传播友好. 这些是可选的, 不影响标准 API 使用.

自动健康检查 · Auto health checks​

master.Build() 时自动跑, 不匹配 → SDK 日志 Warning:

  • 驱动版本比对 — SDK 查询底层实时驱动的内核版本, 跟 SDK 的 MAJOR.MINOR 比对, 不一致即告警
  • RT 核隔离 — 后台检查实时核隔离是否已配置, 缺失则提示重装 SDK

错误码本地化 · Error localization​

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();          // 内核驱动版本

版本兼容​

  • 同 MAJOR.MINOR 内 PATCH 互相兼容 (例 2.1.0 ↔ 2.1.5), 包管理器升级即可, 不需重装驱动
  • MAJOR / MINOR 变化 → 必须重装配套的驱动安装包, 否则会报版本兼容错误