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 10/11 或 Linux
Rust	1.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 — 通过 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 特有语法糖

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 特有语法糖。

自动健康检查

master.Build() 启动时自动校验驱动版本与 RT 核隔离, 不匹配写 Warning 日志。

错误码本地化

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.7。PATCH 兼容、MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。