Python SDK 概述

DarraEtherCAT Python SDK 提供了用于开发 EtherCAT 主站应用程序的 Python 包,支持 Windows 和 Linux 平台,提供主站与从站之间的高速实时通信。

安装

pip install darra-ethercat-master

分发名与导入名

PyPI 分发名为 darra-ethercat-master (pip install 用此名), Python 代码内的导入名为 darra_ethercat (import darra_ethercat)。两者是独立概念 (PEP 427), 不要混用。

手动指定库文件路径

如果原生库不在系统搜索路径中,可以在创建主站时通过 dll_path 参数手动指定路径。SDK 会根据当前操作系统自动选择对应平台的本地库。

系统要求

项目	要求
操作系统	Windows 7+ (推荐 Windows 10/11) 或 Linux
Python	Python 3.12（发布包为 3.12 编译的 .pyc，与 Python 主版本绑定）
网络适配器	常规以太网网卡
权限	管理员权限（Windows）/ root 权限（Linux）

安装 DarraRT 驱动

DarraRT 驱动提供微秒级实时性能，完全免费。详见 下载页面。

平台	驱动类型	说明
Windows	WDK 内核驱动	运行安装包安装内核驱动
Linux	内核模块	运行安装脚本加载内核模块

快速开始

使用 Darra 配置工具

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

from darra_ethercat import EtherCATMaster, EcState

# ★ 推荐方式: 使用 DENI 文件 (Darra 配置工具一键导出)
master = (EtherCATMaster()
          .set_eni(r"C:\EtherCAT\MyProject.deni")
          .build())

master.set_state(EcState.OP)
# 开始通信...

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

不使用 DENI 时, 用 get_network_info() 自动扫描所有网卡, 取有从站的那张:

from darra_ethercat import EtherCATMaster, EcState, get_network_info
from darra_ethercat.utils import DarraCoreDLL

# 扫所有 NIC 并探测从站数 (耗时 ~500ms-1.5s)
dll = DarraCoreDLL()
nets = get_network_info(dll, need_slaves_num=True)

# 选有从站的 NIC (一般只会有一张)
ec = next((n for n in nets if (n.slave_num or 0) > 0), None)
if ec is None:
    raise RuntimeError("未发现 EtherCAT 网络")
print(f"找到: {ec.desc} (从站 {ec.slave_num} 台)")

master = EtherCATMaster().set_network(ec.name).build()
master.set_state(EcState.OP)

何时用哪种

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

上下文管理器（推荐）

from darra_ethercat import EtherCATMaster, EcState

with EtherCATMaster() as master:
    master.set_eni("config.deni")
    count = master.set_network(r"\\Device\\NPF_{GUID}")
    if count > 0:
        master.set_state(EcState.OP)
        master.start()
        # master 退出 with 块时自动调用 close()

一步初始化（JSON 配置）

from darra_ethercat import EtherCATMaster

config = '{"adapter": "\\\\Device\\\\NPF_{GUID}", "target_state": "OP"}'
with EtherCATMaster.from_json(config) as master:
    master.start()
    # ...

高级 API

SDK 提供了一组高级 API，简化常见操作流程：

功能	说明
一步初始化 (from_json/from_json_file)	JSON 配置一步完成主站初始化
状态切换 (set_state)	跨级链式 INIT → PRE_OP → SAFE_OP → OP，每步自动执行启动参数
启动参数管线 (add_startup_param/auto_startup)	批量添加启动参数并自动应用
CiA 402 驱动状态机	使能/故障复位/状态解析
CoE SDO 读写	sdo_read / sdo_write / sdo_read_value / sdo_write_value
PDO 类型化读写	按类型直接读写 PDO 数据（U16/I32/F32 等）
拓扑查询	构建并查询从站网络拓扑树
WDK 实时驱动	微秒级 PDO 周期，零拷贝架构

快速示例:

from darra_ethercat import EtherCATMaster, EcState

with EtherCATMaster() as master:
    count = master.set_network(r"\\Device\\NPF_{GUID}")
    master.set_state(EcState.OP)
    master.start()

    # 访问从站 (1-based 索引)
    slave = master[1]

    # CoE SDO 读写
    status = slave.coe.sdo_read_value(0x6041, 0, dtype='u16')
    slave.coe.sdo_write_value(0x6040, 0, 0x0006, dtype='u16')

    # 拓扑查询
    topo = master.topology
    for node in topo:
        print(f"从站 {node['slave_index']}: 父={node['parent_index']}")

Python 特有语法糖

除标准 API 外, Python SDK 提供 darra_ethercat.sugar 包, 一行 import darra_ethercat.sugar 激活全部 Pythonic 扩展. 详见 Python 特有语法糖 — 包含 with master: 上下文管理器 / for slave in master 迭代 / master[1] 索引 / slave in master 包含查询 / async for diag in slave.coe.diagnostic_stream(): 异步生成器 / @dataclass(frozen=True) SlaveIdentityKey / match state: case OP: 模式匹配 (3.10+) / Protocol 静态类型 / slave.summary() 调试输出. 这些是可选的, 不影响标准 API 使用.

自动健康检查 · Auto health checks

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

• 驱动版本比对 — SDK 读取已安装内核驱动的版本, 跟 SDK MAJOR.MINOR 比, 不一致告警
• RT 核隔离 — 检查 RT 核隔离是否已就绪, 缺失提示重装 SDK

错误码本地化 · Error localization

AL Status 描述双语. SDK 默认英文, 中文专用接口给 UI:

from darra_ethercat.statics.print import describe_al_status
from darra_ethercat.utils.driver_version import get_driver_version

en = describe_al_status(code)        # English (default)
drv = get_driver_version(dll)        # 内核驱动版本 dict

版本兼容

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

2.5.x 主要变更

类别	内容
新增	MDP 模块化设备自动编排 (GCAN-8200 等模块化设备进 OP 时自动配置, 见 MDP)
新增	异步邮箱事务 API MailboxTransaction (G-5 真异步 Worker, 见 邮箱网关)
新增	从站实时状态查询 GetSlaveStateLive / GetSlaveALStatusCodeLive (绕开周期缓存直读总线)
新增	per-group 期望 WKC 访问器 master.get_group_expected_wkc(group)
新增	SoE IDN 编解码 native 对齐 (encode_idn / decode_idn, 与 DLL SoEIdnEncode/Decode 逐位等价)
修正	has_esi_dc_sync 走真实 ESI DC OpMode 声明; DC 能力门按 ESI 真实声明
修正	从站 PDO 字节属性 (ibytes / obytes 等) 修正为正确的 native 导出名
移除	死/幽灵 API: PDO 周期统计系列、QuickSlaveCountRedundant、ScanSlaveCount*、SetStateCacheUpdateInterval 等 (详见各章节)