Metadata-Version: 2.4
Name: Darra_EtherCAT_Master
Version: 2.10.0
Summary: EtherCAT 主站协议栈 Python SDK · 全协议 (CoE/SoE/FoE/EoE/AoE/VoE/FSoE) + CiA 402/401 · DC 同步 · 电缆冗余 + 热插拔 · 复杂拓扑 · 搭配 DarraRT 实时内核驱动达微秒级帧时序 · Windows/Linux · EtherCAT master protocol stack for Python: full mailbox protocols, CiA 402/401, distributed clocks, cable redundancy, hot-plug, complex topology; microsecond frame timing with the DarraRT real-time driver.
Author-email: Darra Technology <dev@darra.xyz>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://ethercat.darra.xyz
Project-URL: Documentation, https://ethercat.darra.xyz/doc/sdk/python
Project-URL: Repository, https://ethercat.darra.xyz
Project-URL: Changelog, https://ethercat.darra.xyz/changelog
Keywords: ethercat,industrial-automation,plc,motion-control,fieldbus,real-time,cia402,coe,fsoe,darra,darrart,robotics,servo,kernel-driver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center"><img src="https://download.darra.xyz/ethercat/static/icon.png" alt="Darra EtherCAT Master" width="96" height="96"></p>

# Darra EtherCAT Master · Python SDK

Python 语言的 EtherCAT 主站 SDK：全部 7 种邮箱协议、CiA 402 / 401、DC 分布式时钟、电缆冗余与复杂拓扑，搭配 DarraRT 实时内核驱动。6 种语言 SDK 行为一致。

*EtherCAT master SDK for Python — all 7 mailbox protocols, CiA 402 / 401, Distributed Clocks, cable redundancy and complex topologies; with the DarraRT real-time driver. Six-language SDKs behave the same.*

---

## 能力 · Capabilities

帧发送周期抖动实测（配 DarraRT 实时内核驱动）：

| 平台 / Platform | 建议周期 / Cycle | 帧抖动(平均) / Jitter | 最大抖动 / Max |
|---|---|---|---|
| Windows 10 IoT (SMI 抑制) | 62.5 µs | 1.0 µs | 4.2 µs |
| Linux PREEMPT_RT | 62.5 µs | 0.7 µs | 3.2 µs |
| FreeRTOS | 31.25 µs | 0.3 µs | 2 µs |

- 最小周期 **31.25 µs** · DC 同步 **≤ 1 µs** · 0 拷贝 PDO
- **全邮箱协议** — CoE · SoE · FoE · EoE · AoE · VoE · FSoE
- **驱动配置** — CiA 402（CSP / CSV / CST / PP / PV / HM）+ CiA 401
- **实时与拓扑** — 电缆冗余 · 线 / 星 / 树 / 环
- **6 语言一致** — C / C++ / C# / Java / Python / Rust，同一 Core

---

## 开始 · Get started

1. 先安装官方安装包（实时内核驱动 + 配置工具）：[下载页](https://ethercat.darra.xyz/doc/downloads) · https://download.darra.xyz/ethercat/client/Darra-EtherCAT-Setup.exe
2. 本包是 Python SDK：

```bash
pip install darra-ethercat-master
```

3. 新人：[基础知识](https://ethercat.darra.xyz/doc/ethercat/beginner-guide) · [从配置工具开始](https://ethercat.darra.xyz/doc/quick-start/from-master-tools) · [从 SDK 继续](https://ethercat.darra.xyz/doc/quick-start/from-sdk) · [Python 文档](https://ethercat.darra.xyz/doc/sdk/python)

**升级 / 重装**：先**卸载**旧版 → **重启**电脑 → 再**安装**新版。操作前请先保存好工程和配置文件。

---

## 最佳用法

总线周期由内核完成。进 OP 后把 PDO 映射成结构体，之后当普通变量读写即可——任意线程可用，不用自开实时循环。

```python
import ctypes
from darra_ethercat import EtherCATMaster, EcState

class InPdo(ctypes.Structure):
    _pack_ = 1
    _fields_ = [("status_word", ctypes.c_uint16),
                ("actual_position", ctypes.c_int32)]

class OutPdo(ctypes.Structure):
    _pack_ = 1
    _fields_ = [("control_word", ctypes.c_uint16),
                ("target_position", ctypes.c_int32)]

master = (EtherCATMaster()
          .set_eni(r"C:\EtherCAT\MyProject.deni")
          .build())
master.set_state(EcState.OP)
slave = master.slaves[0]          # 列表式索引: slaves[0] = 第 1 台 (方法式 master.slave(1) 同为第 1 台)
inp = slave.pdo.inputs_mapping(InPdo)
outp = slave.pdo.outputs_mapping(OutPdo)

outp.control_word = 0x000F
outp.target_position = 100_000
status = inp.status_word
```

---

## 邮箱 · CoE (SDO)

按索引/子索引读写对象字典（邮箱往返，非周期）：

```python
slave = master.slaves[0]
data = slave.coe.sdo_read(0x6041, 0)                      # 读 StatusWord
if data is None:                                          # 失败返回 None (对象为空是 b"", 不是失败)
    raise RuntimeError(f"SDO 读失败: {slave.coe.last_sdo_error}")   # 先判失败, 再取值
status = int.from_bytes(data[:2], "little")

pos = slave.coe.sdo_read(0x6064, 0)                       # 读 ActualPosition
if pos is None:
    raise RuntimeError(f"SDO 读失败: {slave.coe.last_sdo_error}")
position = int.from_bytes(pos[:4], "little", signed=True)

if not slave.coe.sdo_write(0x607A, 0, (100000).to_bytes(4, "little", signed=True)):  # 写 TargetPosition
    raise RuntimeError(f"SDO 写失败: {slave.coe.last_sdo_error}")   # 判返回值
```

---

## 属性 · Properties

| 属性 | 类别 | 读写 | 说明 |
|---|---|---|---|
| `master_number` | 基本信息 | 只读 | 主站实例编号 |
| `slave_count` | 基本信息 | 只读 | 网络中检测到的从站数量 |
| 是否已初始化 | 基本信息 | 只读 | 主站是否已初始化 (待核) |
| `is_disposed` | 基本信息 | 只读 | 主站是否已释放 |
| 是否冗余模式 | 基本信息 | 只读 | 是否冗余模式 (待核) |
| `link_state` | 网络与链路 | 只读 | 网络链路状态 |
| `error_code` | 错误码 | 只读 | 异常时的自动报警错误码 |
| `error_cnt` | 错误码 | 只读 | 错误计数 |
| `master_dc_time` | DC 与周期 | 只读 | DC 时间戳（纳秒） |
| `loop_cycle` | DC 与周期 | 读写 | PDO 周期时间（纳秒） |
| `state` | 运行时 | 只读 | 主站 EtherCAT 状态 |
| `wkc` | 运行时 | 只读 | 工作计数器 (WKC) |
| `expected_wkc` | 运行时 | 只读 | 期望工作计数器 |
| 主网卡 WKC | 运行时 | 只读 | 冗余模式下主网卡 WKC (待核) |
| 备网卡 WKC | 运行时 | 只读 | 冗余模式下备网卡 WKC (待核) |
| `reference_clock_slave_index` | 运行时 | 只读 | 参考时钟从站索引 (0 = 无) |
| `divider` | 分组 | 读写 | 组循环分频器 |
| `active_group_count` | 分组 | 只读 | 活跃组数量 |
| `filter_threshold` | 分组 | 读写 | 判断滤波阈值 |
| `get_api_version()` | 版本 | 只读 | SDK/API 版本号（实测入口 get_api_version()） |
| `dll_version` | 版本 | 只读 | 内核 DLL 版本，含 major/minor/patch/build/build_date |

---

## 版本兼容 · Version compatibility

| 升级类型 | 需更新配套驱动? |
|---|---|
| **PATCH** (X.Y.1 → X.Y.2) | 不需要 |
| **MINOR / MAJOR** (X.Y.x → X.(Y+1).0 / (X+1).0.0) | 需要 |

---

## 其它语言 · Other SDKs

| 语言 / Language | 包 / Package | 来源 / Source |
|---|---|---|
| C | `darra_ethercat_c-win-x64.zip` | [下载页](https://ethercat.darra.xyz/doc/downloads) |
| C++ | `darra_ethercat_cpp-win-x64.zip` | [下载页](https://ethercat.darra.xyz/doc/downloads) |
| C# | `Darra.EtherCAT.Master` | NuGet |
| Java | `xyz.darra:darra-ethercat-master` | Maven Central |
| Python | `darra-ethercat-master` | PyPI（本包 / this SDK） |
| Rust | `darra-ethercat-master` | crates.io |

## 许可 · License

专有软件 · Proprietary — © Darra Technology，使用须遵守随产品提供的许可协议。
