Metadata-Version: 2.4
Name: Darra_EtherCAT_Master
Version: 2.9.140
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

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

*Python SDK for the Darra EtherCAT master stack — 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]
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:
    status = int.from_bytes(data[:2], "little")
slave.coe.sdo_write(0x607A, 0, (100000).to_bytes(4, "little", signed=True))  # 写 TargetPosition
```

---

## 其它语言 · 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，使用须遵守随产品提供的许可协议。
