跳到主要内容

Python SDK 概述

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

安装​

pip install darra-ethercat

或从源码安装：

git clone https://github.com/Darra/darra-ethercat-python.git
cd darra-ethercat-python
pip install -e .
手动指定库文件路径

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

系统要求​

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

安装 DarraRT 驱动​

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

平台驱动类型说明
WindowsWDK 内核驱动安装 DarraRT.sys 驱动
LinuxLKM 内核模块加载 DarraRT.ko 内核模块

快速开始​

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

# 推荐方式：使用 DENI 文件 + 链式调用
with EtherCATMaster() as master:
    # Windows
    master.set_eni(r"C:\EtherCAT\MyProject.deni")
    slave_count = master.set_network(r"\\Device\\NPF_{GUID}")

    # Linux
    # master.set_eni("/opt/ethercat/MyProject.deni")
    # slave_count = master.set_network("eth0")

    if slave_count > 0:
        master.set_state(EcState.OP)
        master.start()
        # 开始通信...

上下文管理器（推荐）​

from 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 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 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']}")