Darra-EtherCAT-Master 1.99.7

商业 EtherCAT 主站协议栈 · 实时内核驱动 · 抖动 1µs · Windows + Linux · 多编程语言 · 全协议 · 支持复杂拓扑 + 热插拔 · ethercat.darra.xyz · Commercial EtherCAT Master protocol stack · Real-time kernel driver · 1µs jitter · Multi-platform · Multi-language · Complex topology + hot-plug.

Darra EtherCAT Master · Python SDK

商业 EtherCAT 主站协议栈 · 功能齐全 · 易于集成 · 高可靠 Commercial EtherCAT master protocol stack · Feature-complete · Easy to integrate · High reliability

[ Windows · Linux · MCU ] [ 6 语言 SDK / 6 languages ] [ 全协议含 FSoE / Full mailbox + FSoE ] [ 冗余 + 热插拔 + 三级自愈 / Redundancy + hot-plug + 3-level recovery ] [ ethercat.darra.xyz ]

---

为什么选 Darra

围绕三件事打磨:功能齐全 · 使用方便 · 高可靠.

	SOEM 开源	专用主站板卡	Darra EtherCAT
— 功能齐全 —
邮箱协议	CoE / EoE / FoE	视厂商	全 7 协议: CoE · EoE · FoE · SoE · AoE · VoE · FSoE (SIL3)
高级特性	DC, 冗余需自实现	视厂商	DC + Hot-Connect + 邮箱网关 (ETG.8200) + CiA402 状态机
拓扑	线 / 树	视厂商	线 / 树 / 环 / 分支 / 星 + 热插拔
— 使用方便 —
SDK 语言	C 一种	厂商专用 SDK	6 种字节级一致 (C / C++ / C# / Java / Python / Rust)
安装	自行编译集成	配套硬件 + 厂商 IDE	包管理器一行: dotnet add / pip install / cargo add / Maven
配置	手工写代码	厂商配置工具	图形化工具一键导出 ENI / DENI + 多语言示例自动生成
文档	社区 / 源码	厂商手册	6 语言一致 SDK 在线文档 + 示例
— 高可靠 —
实时抖动	视用户 RT 系统	硬件保障	配 DarraRT ≤ 1 µs (Windows / Linux PREEMPT_RT)
冗余	用户自实现	视厂商	零丢帧切换 + 三级故障自愈 (L1 冗余 / L2 降级 / L3 热插拔)
功能安全	—	视厂商	FSoE (SIL3) 协议栈
诊断	基础	视厂商	ETG.1510 在线诊断 + EMCY 历史 + 实时抖动统计

Why Darra

Built around three goals: feature-complete · easy to use · highly reliable.

	SOEM (Open-source)	Dedicated master card	Darra EtherCAT
— Feature-complete —
Mailbox	CoE / EoE / FoE	Vendor-dependent	All 7: CoE · EoE · FoE · SoE · AoE · VoE · FSoE (SIL3)
Advanced	DC, redundancy DIY	Vendor-dependent	DC + Hot-Connect + Mailbox Gateway (ETG.8200) + CiA402 FSM
Topology	Line / tree	Vendor-dependent	Line / tree / ring / branch / star + hot-plug
— Easy to use —
Languages	C only	Vendor-specific SDK	6 byte-consistent (C / C++ / C# / Java / Python / Rust)
Install	Build & integrate yourself	Hardware + vendor IDE	One-line via package manager: dotnet add / pip install / cargo add / Maven
Config	Hand-coded	Vendor config tool	GUI tool exports ENI / DENI + multi-language example auto-generation
Docs	Community / source	Vendor manual	Unified online SDK docs + examples for 6 languages
— High reliability —
RT jitter	Depends on user RT stack	Hardware-guaranteed	≤ 1 µs with DarraRT (Windows / Linux PREEMPT_RT)
Redundancy	User-implemented	Vendor-dependent	Zero frame loss + 3-level recovery (L1 redundancy / L2 degrade / L3 hot-plug)
Safety	—	Vendor-dependent	FSoE (SIL3) protocol stack
Diagnostics	Basic	Vendor-dependent	ETG.1510 live diagnostics + EMCY history + jitter stats

---

核心能力 · Key capabilities

初始化 · Initialization

三种方式按场景选用. Three init paths to fit common scenarios.

• 🟢 DENI 文件 / DENI file (★ 生产推荐 / Recommended) — Darra 配置工具一键导出 ESI/PDO/DC/启动参数, 1 行加载. Exported by the Darra GUI tool with all ESI / PDO / DC / startup preset; load in one line.
• 🟡 ESI 目录 + 自动配 / ESI dir + auto-config — 给 ESI 库, SDK 按从站身份自动套默认参数. Pass an ESI library; the SDK auto-applies defaults per slave identity.
• 🟠 纯自动配 / Pure auto-config — 无 ESI 也可, 用从站 CoE 对象字典自动配 (调试 / 演示场景). Works without ESI by reading the slave's own CoE object dictionary (debug / demo).

协议与可靠性 · Protocols & reliability

• 全 7 邮箱协议 / All 7 mailbox protocols — CoE · EoE · FoE · SoE · AoE · VoE · FSoE (SIL3).
• DC 分布式时钟 / Distributed Clocks — ≤ 1 µs 同步, 静态 + 动态偏移补偿 (配 DarraRT). Sub-µs sync with static + dynamic offset compensation (with DarraRT).
• 冗余 + Hot-Connect / Redundancy + Hot-Connect — 双链路单周期切换, 环 / 分支拓扑, 零丢帧. Single-cycle dual-link failover, ring / branch topology, zero frame loss.
• 三级故障自愈 / 3-level recovery — L1 冗余切换 · L2 通信降级 · L3 热插拔身份验证 + CoE 重入 PreOP. L1 redundancy / L2 degrade / L3 hot-plug identity verification + CoE re-enter PreOP.
• 诊断 / Diagnostics (ETG.1510) — 32-bit CRC + 断线定位 + AL Status 解析 + 紧急消息历史 + 实时抖动统计. 32-bit CRC + link-loss locating + AL Status parsing + EMCY history + live jitter stats.

高级 API · High-level APIs

• 一步初始化 / One-step init EcInit — 把 Initialize + SetNetwork + LoadConfig + SetStateSequence + Start 五步一行解决. Collapses 5 steps into a single call.
• 状态链 / State chain SetState(OP) — 自动 INIT → PreOp → SafeOp → OP, 失败回退诊断. Auto INIT → PreOp → SafeOp → OP with failure diagnostics.
• 启动参数管线 / Startup parameter pipeline — 批量添加 SDO 启动参数, 状态切换时一次写入. Batch SDO startup parameters, applied on state transition.
• CiA402 驱动状态机 / CiA402 drive FSM — 一行使能 / 故障复位, 自动解析驱动状态字. One-line enable / fault-reset; auto-parses the drive statusword (Switch on / Operation enabled / Fault).
• PDO 类型化读写 / Typed PDO I/O — 按 U16 / I32 / F32 / 结构体直接读写, 自动字节序处理. Read / write by U16 / I32 / F32 / structs with automatic endianness.
• 邮箱网关 / Mailbox Gateway — ETG.8200 透传, 兼容 TwinCAT / 第三方工具远程访问 SDO. ETG.8200 pass-through compatible with TwinCAT and 3rd-party SDO tools.
• 拓扑查询 / Topology query — 实时构建从站网络拓扑树, 含分支 / 环识别. Real-time slave network tree with branch / ring detection.

---

Install

pip install darra-ethercat-master

要求: Python 3.12 · Windows 10/11 x64 · 首次运行需以管理员安装 DarraRT 实时内核驱动 (SDK 强制依赖, 兼容硬件).

---

快捷使用 · Quick start

最简流程: DENI 一行加载 → 进 OP → 邮箱基本读写.

from darra_ethercat import EtherCATMaster, EcState

master = (EtherCATMaster()
          .set_eni(r"C:\EtherCAT\MyProject.deni")   # DENI 一行加载
          .build())

master.set_state(EcState.OP)                         # 自动 INIT → PreOp → SafeOp → OP

# 邮箱读 — 两种风格任选:

#  ① 基本: bytes + 手动解析
data = master.slaves[0].coe.sdo_read(0x6041, 0x00)
statusword = int.from_bytes(data[:2], 'little')

#  ② 高级: 对象字典索引器 + 类型化 (一行)
sw = master.slaves[0].coe[0x6041][0x00].get_value()

# 邮箱基本写: 字节版
master.slaves[0].coe.sdo_write((100_000).to_bytes(4, 'little'), sub_index=0x00)

---

高级使用 · Advanced

自动搜网卡 + ESI 自动配 · 类型化邮箱写 (无需 byte-pack) · CiA402 / 邮箱网关 / 诊断.

from darra_ethercat import EtherCATMaster, EcState, get_network_info

# ① 自动搜网卡 (取有从站的那张 NIC)
nets = get_network_info(need_slaves_num=True)
ec = next((n for n in nets if (n.slave_num or 0) > 0), None)
if ec is None:
    raise RuntimeError("未发现 EtherCAT 网络")

# ② ESI 目录 + 自动配 (无 DENI 场景)
master = (EtherCATMaster()
          .set_esi_files(r"C:\Esi")        # ESI 目录, SDK 按身份自动套默认参数
          .set_network(ec.name)
          .enable_auto_startup()
          .build())

master.set_state(EcState.OP)

# ③ 类型化邮箱读写 (无需手动 byte-pack, 自动 little-endian)
status = master.slaves[0].coe.sdo_read_value(0x6041, 0x00, dtype='u16')
master.slaves[0].coe.sdo_write_value(0x607A, 0x00, 100_000, dtype='i32')

# ④ CiA402 驱动一步使能 (Switch on → Operation enabled)
master.slaves[0].cia402.enable()

# ⑤ 诊断快照 (帧率 / 错误率)
diag = master.diagnostics_info
print(f"频率 {diag.frequency} Hz, 错误 {diag.error_count}")

# ⑥ 邮箱网关 (TwinCAT / 第三方工具远程透传 SDO, ETG.8200)
master.mailbox_gateway.start()
print(f"网关运行在端口 {master.mailbox_gateway.port}")

更多 API · More APIs — 完整参考: https://ethercat.darra.xyz/docs/sdk/python

---

6 语言 SDK 家族 · 6-language SDK family

字节级一致的 CRC / 枚举 / 错误码,业务代码可平滑跨语言。

Language	Package	Registry
Python	darra-ethercat-master	PyPI
C#	Darra.EtherCAT.Master	NuGet
Java	xyz.darra:darra-ethercat-master	Maven Central
Rust	darra-ethercat-master	crates.io
C / C++	darra-ethercat-c / darra-ethercat-cpp	Releases

---

文档 · Documentation

• 官网 · Homepage: https://ethercat.darra.xyz
• Python SDK 文档: https://ethercat.darra.xyz/docs/sdk/python
• 快速开始: https://ethercat.darra.xyz/docs/quick-start
• 协议详解: https://ethercat.darra.xyz/docs/ethercat
• 应用案例: https://ethercat.darra.xyz/docs/examples

⚠️ 关于"微秒级"实时性能 · About microsecond real-time 本 SDK 强制配合 DarraRT 实时内核驱动 + 兼容硬件 使用. 微秒级实时由 SDK + DarraRT 共同提供. DarraRT 通过 CPU 核心隔离 + I/O APIC 中断重定向 + LVT 屏蔽 + 干净抖动统计 显著降低 SMI 干扰 (但不能完全抑制, SMM 属硬件层中断, 完全抑制需 BIOS/UEFI 配合). DarraRT 需另行安装 (非自动安装); SDK 启动时若未检测到, 会提示获取下载链接. 我们另提供 硬实时隔离部署方案, 满足更严苛的实时与功能安全需求. 详见 DarraRT 驱动说明.

This SDK requires the DarraRT real-time kernel driver and supported hardware as runtime companions. Microsecond-level performance is delivered by SDK + DarraRT together. DarraRT mitigates SMI via CPU core isolation, I/O APIC redirect, LVT masking, and clean jitter accounting, though it cannot fully suppress SMI (SMM is a hardware-level interrupt; full suppression requires BIOS/UEFI tuning). DarraRT must be installed separately (not auto-installed); the SDK prompts a download link on startup if not detected. A hard real-time isolated deployment is also available for stricter real-time and functional-safety requirements.

---