跳到主要内容

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 10/11 或 Linux
PythonPython 3.12（发布包为 3.12 编译的 .pyc，与 Python 主版本绑定）
权限管理员（Windows）/ root（Linux）
实时驱动需安装实时内核驱动（随安装包，见 Windows 驱动）

快速开始​

使用 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​

简化常见操作的一组高级 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 特有语法糖​

import darra_ethercat.sugar 激活可选的 Pythonic 扩展 (不影响标准 API): 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() 调试输出。详见 Python 特有语法糖。

自动健康检查​

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

错误码本地化​

AL Status 描述双语 (默认英文, 中文接口给 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。PATCH 兼容、MINOR/MAJOR 必须重装配套驱动 —— 详见 SDK 版本兼容。

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, 与底层库逐位等价)
修正has_esi_dc_sync 走真实 ESI DC OpMode 声明; DC 能力门按 ESI 真实声明
修正从站 PDO 字节属性 (ibytes / obytes 等) 命名与底层库对齐
移除死/幽灵 API: PDO 周期统计系列、QuickSlaveCountRedundant、ScanSlaveCount*、SetStateCacheUpdateInterval 等 (详见各章节)