Metadata-Version: 2.4
Name: Darra_EtherCAT_Master
Version: 2.7.1
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: Proprietary
Project-URL: Homepage, https://ethercat.darra.xyz
Project-URL: Documentation, https://ethercat.darra.xyz/docs/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: License :: Other/Proprietary License
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
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown

<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; microsecond-level frame timing with the DarraRT real-time driver.*

---

## 性能 · Performance

帧发送周期抖动实测（配 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** · 零拷贝 PDO 映射
- DENI 文件加载比从零扫描快约 **50%**（实测 7.4 s vs 15.2 s）

> 微秒级实时由 SDK + DarraRT 实时内核驱动 + 兼容硬件共同提供。SMI/SMM 属硬件层中断，完全抑制需 BIOS/UEFI 配合。
> *Microsecond timing is delivered by the SDK together with the DarraRT real-time driver and supported hardware; full SMI suppression requires BIOS/UEFI tuning.*

---

## 能力 · Capabilities

- **全邮箱协议** — CoE (SDO/PDO/EMCY/CiA402) · SoE · FoE · EoE · AoE · VoE · FSoE（功能安全 SIL3）
- **驱动配置** — CiA 402 全模式 (CSP/CSV/CST/PP/PV/HM) + CiA 401 数字/模拟 I/O
- **可靠性** — 电缆冗余零丢帧切换 · 三级故障自愈（不停 PDO 循环）· 运行中热插拔
- **复杂拓扑** — 线 / 星 (EK1122) / 树 (EK1100) / 环 / 混合
- **在线诊断** — 从站状态 / AL Status Code / PDO 值实时可读 · 周期抖动统计 (ETG.1510)
- **邮箱网关** — ETG.8200，兼容 TwinCAT 等第三方工具
- **6 语言一致** — C / C++ / C# / Java / Python / Rust，枚举 / 错误码 / CRC 字节级一致

---

## 安装 · Install

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

> 要求：Python 3.12 · Windows 10/11 x64 · 需安装 DarraRT 实时内核驱动（随安装包，首次以管理员运行）。
> *Requires Python 3.12, Windows 10/11 x64, and the DarraRT real-time kernel driver (bundled in the installer).*

---

## 示例 · Example

DENI 一行加载 → 进 OP → PDO / 邮箱读写：

```python
from darra_ethercat import EtherCATMaster, EcState

master = (EtherCATMaster()
          .set_eni(r"C:\EtherCAT\MyProject.deni")   # 配置工具一键导出的 DENI
          .build())

master.set_state(EcState.OP)                         # 自动 INIT → PreOp → SafeOp → OP

# 过程数据 (PDO)：进 OP 后内核每周期自动收发，循环里直接访问最新值
slave = master.slaves[0]
statusword = slave.pdo.read_uint16(0)                # 读输入 (TxPDO)
slave.pdo.write_int32(0, 100_000)                    # 写输出 (RxPDO)，下一周期自动发出

# 非周期邮箱 (CoE SDO)
target = slave.coe[0x607A][0x00].get_value()         # 类型化读
```

---

## 版本兼容 · Version compatibility

| 升级 / Upgrade | 重装驱动? / Reinstall driver? |
|---|---|
| PATCH (X.Y.1 → X.Y.2) | ❌ `pip install --upgrade` 即可 |
| MINOR / MAJOR | ✅ 需同步更新配套驱动安装包 |

`master.build()` 启动时自动校验 SDK 与驱动版本，不匹配写日志 Warning。

---

## 更多 · More

- **Python SDK 文档 / Docs** — <https://ethercat.darra.xyz/docs/sdk/python>
- **官网 / Homepage** — <https://ethercat.darra.xyz>
- **应用案例 / Examples** — <https://ethercat.darra.xyz/docs/examples>
