soemx 0.1.0__tar.gz

soemx-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md pyproject.toml setup.py
+recursive-include soemx *.py *.pyx *.c *.h
+recursive-include tests *.py
+recursive-include vendor/SOEM/include *.h *.in
+recursive-include vendor/SOEM/src *.c *.h
+recursive-include vendor/SOEM/osal/linux *.c *.h
+recursive-include vendor/SOEM/osal/win32 *.c *.h
+include vendor/SOEM/osal/osal.h
+recursive-include vendor/SOEM/oshw/linux *.c *.h
+recursive-include vendor/SOEM/oshw/win32 *.c *.h
+recursive-include vendor/SOEM/build/include *.h

soemx-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: soemx
+Version: 0.1.0
+Summary: Cython bindings for SOEM with EoE support
+Author: soemx contributors
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# soemx
+
+[![CI](https://github.com/11cookies11/soemx/actions/workflows/ci.yml/badge.svg)](https://github.com/11cookies11/soemx/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/soemx.svg)](https://pypi.org/project/soemx/)
+[![Python](https://img.shields.io/pypi/pyversions/soemx.svg)](https://pypi.org/project/soemx/)
+
+`soemx` 是一个面向个人项目和工业自动化实验的 SOEM Python 封装，使用
+Cython 将 SOEM 2.x 的 EtherCAT Master 能力暴露给 Python，并额外提供 EoE
+（Ethernet over EtherCAT）接口。
+
+项目仍在积极开发中，API 可能发生变化。没有 EtherCAT 硬件时，可以运行构建
+和单元测试；真实的 PDO、Mailbox 和 EoE 通信需要兼容的网卡和从站设备。
+
+Python bindings for the [Simple Open EtherCAT Master (SOEM)](https://github.com/OpenEtherCATsociety/SOEM), implemented with Cython.
+
+The project is intended to provide a complete, Python-friendly API for EtherCAT master operations, including EoE (Ethernet over EtherCAT), which is not currently exposed by PySOEM.
+
+## Installation
+
+```powershell
+python -m pip install soemx
+```
+
+当前 PyPI 发布的是开发版本。没有对应平台 wheel 时，pip 会从源码构建扩展，
+因此 Linux 需要 C 编译器、Cython 和 `libpcap-dev`；Windows 需要 Visual Studio
+C++ 构建工具以及运行时使用的 Npcap（WinPcap API 兼容模式）。
+
+## Current API
+
+The Cython extension currently provides:
+
+- `Master.open()` / `close()` and context-manager support, including optional redundancy
+- `find_adapters()` returning `Adapter` objects with `name` and `desc` attributes
+- slave discovery, state control, AL diagnostics and EEPROM access
+- mapped process data through `Master.io_map`, `Slave.inputs` and `Slave.outputs`
+- cyclic and grouped process-data exchange, one-shot `exchange_processdata()` /
+  `exchange_processdata_group()`, direct `rxpdo()` / `txpdo()` access
+- actual PDO map length through `Master.mapped_size`, plus writable memory views
+- SDO / CoE, SDO information discovery, FoE and SoE
+- configurable default SDO read/write timeouts through `Master`
+- consistent GIL release for blocking native operations through
+  `Master.always_release_gil` and `Master.check_release_gil()`
+- EoE frame send/receive and raw mailbox transport
+- distributed clocks, DC sync0, overlap/packed mapping and queued errors
+- parsed slave mailbox parameters (`mailbox_out_address`, `mailbox_out_size`,
+  `mailbox_in_address`, `mailbox_in_size`) for diagnostics
+- mailbox layout updates through `Slave.amend_mbx()` before mailbox use
+
+PySOEM is used as a practical API reference, but `soemx` is free to improve the
+interface where a clearer or safer design is possible. Raw byte-oriented methods
+are used where Python cannot know a device's object data type. In addition to
+normal slave-indexed EEPROM access, the master exposes direct AP and FP EEPROM
+operations for diagnostics.
+
+EoE channels accept any bytes-like frame buffer and expose IPv4 configuration
+through `set_ip()` / `get_ip()`. Emergency mailbox notifications are delivered
+as structured `Emergency` objects through Master-level or per-slave callbacks.
+Raw records from `pop_error()` retain the associated register and auxiliary
+word fields for diagnostics.
+
+## Build and runtime
+
+Build the extension on Windows with Visual Studio and Cython:
+
+```powershell
+python setup.py build_ext --inplace
+python -m pytest -q
+```
+
+Linux builds use SOEM's raw-socket backend and require the system `libpcap`
+development package and a compiler.
+
+The Windows backend links against Npcap/WinPcap's `wpcap.dll` and `Packet.dll`.
+These DLLs are required when opening a network adapter, but pure Python modules
+and the test suite can be used without EtherCAT hardware or the packet runtime.
+
+Physical EtherCAT, PDO, mailbox and EoE behavior still requires a compatible
+network adapter and at least one EtherCAT slave.
+
+## Minimal EoE example
+
+```python
+import soemx
+
+for adapter in soemx.find_adapters():
+    print(adapter.name, adapter.desc)
+
+with soemx.open("YOUR_INTERFACE") as master:
+    if master.config_init() <= 0:
+        raise RuntimeError("no EtherCAT slaves found")
+    channel = master.slaves[0].eoe()
+    channel.set_ip(b"192.168.1.20", b"255.255.255.0", b"192.168.1.1")
+    ethernet_frame = b"replace with a complete Ethernet frame"
+    channel.send(ethernet_frame)
+    frame = channel.receive()
+```
+
+The example requires an EoE-capable slave and a WinPcap-compatible Npcap
+installation on Windows (or the Linux packet-capture development package).
+
+SOEM is included under `vendor/SOEM` for development and is licensed separately. See its `LICENSE.md`.

soemx-0.1.0/README.md

@@ -0,0 +1,101 @@
+# soemx
+
+[![CI](https://github.com/11cookies11/soemx/actions/workflows/ci.yml/badge.svg)](https://github.com/11cookies11/soemx/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/soemx.svg)](https://pypi.org/project/soemx/)
+[![Python](https://img.shields.io/pypi/pyversions/soemx.svg)](https://pypi.org/project/soemx/)
+
+`soemx` 是一个面向个人项目和工业自动化实验的 SOEM Python 封装，使用
+Cython 将 SOEM 2.x 的 EtherCAT Master 能力暴露给 Python，并额外提供 EoE
+（Ethernet over EtherCAT）接口。
+
+项目仍在积极开发中，API 可能发生变化。没有 EtherCAT 硬件时，可以运行构建
+和单元测试；真实的 PDO、Mailbox 和 EoE 通信需要兼容的网卡和从站设备。
+
+Python bindings for the [Simple Open EtherCAT Master (SOEM)](https://github.com/OpenEtherCATsociety/SOEM), implemented with Cython.
+
+The project is intended to provide a complete, Python-friendly API for EtherCAT master operations, including EoE (Ethernet over EtherCAT), which is not currently exposed by PySOEM.
+
+## Installation
+
+```powershell
+python -m pip install soemx
+```
+
+当前 PyPI 发布的是开发版本。没有对应平台 wheel 时，pip 会从源码构建扩展，
+因此 Linux 需要 C 编译器、Cython 和 `libpcap-dev`；Windows 需要 Visual Studio
+C++ 构建工具以及运行时使用的 Npcap（WinPcap API 兼容模式）。
+
+## Current API
+
+The Cython extension currently provides:
+
+- `Master.open()` / `close()` and context-manager support, including optional redundancy
+- `find_adapters()` returning `Adapter` objects with `name` and `desc` attributes
+- slave discovery, state control, AL diagnostics and EEPROM access
+- mapped process data through `Master.io_map`, `Slave.inputs` and `Slave.outputs`
+- cyclic and grouped process-data exchange, one-shot `exchange_processdata()` /
+  `exchange_processdata_group()`, direct `rxpdo()` / `txpdo()` access
+- actual PDO map length through `Master.mapped_size`, plus writable memory views
+- SDO / CoE, SDO information discovery, FoE and SoE
+- configurable default SDO read/write timeouts through `Master`
+- consistent GIL release for blocking native operations through
+  `Master.always_release_gil` and `Master.check_release_gil()`
+- EoE frame send/receive and raw mailbox transport
+- distributed clocks, DC sync0, overlap/packed mapping and queued errors
+- parsed slave mailbox parameters (`mailbox_out_address`, `mailbox_out_size`,
+  `mailbox_in_address`, `mailbox_in_size`) for diagnostics
+- mailbox layout updates through `Slave.amend_mbx()` before mailbox use
+
+PySOEM is used as a practical API reference, but `soemx` is free to improve the
+interface where a clearer or safer design is possible. Raw byte-oriented methods
+are used where Python cannot know a device's object data type. In addition to
+normal slave-indexed EEPROM access, the master exposes direct AP and FP EEPROM
+operations for diagnostics.
+
+EoE channels accept any bytes-like frame buffer and expose IPv4 configuration
+through `set_ip()` / `get_ip()`. Emergency mailbox notifications are delivered
+as structured `Emergency` objects through Master-level or per-slave callbacks.
+Raw records from `pop_error()` retain the associated register and auxiliary
+word fields for diagnostics.
+
+## Build and runtime
+
+Build the extension on Windows with Visual Studio and Cython:
+
+```powershell
+python setup.py build_ext --inplace
+python -m pytest -q
+```
+
+Linux builds use SOEM's raw-socket backend and require the system `libpcap`
+development package and a compiler.
+
+The Windows backend links against Npcap/WinPcap's `wpcap.dll` and `Packet.dll`.
+These DLLs are required when opening a network adapter, but pure Python modules
+and the test suite can be used without EtherCAT hardware or the packet runtime.
+
+Physical EtherCAT, PDO, mailbox and EoE behavior still requires a compatible
+network adapter and at least one EtherCAT slave.
+
+## Minimal EoE example
+
+```python
+import soemx
+
+for adapter in soemx.find_adapters():
+    print(adapter.name, adapter.desc)
+
+with soemx.open("YOUR_INTERFACE") as master:
+    if master.config_init() <= 0:
+        raise RuntimeError("no EtherCAT slaves found")
+    channel = master.slaves[0].eoe()
+    channel.set_ip(b"192.168.1.20", b"255.255.255.0", b"192.168.1.1")
+    ethernet_frame = b"replace with a complete Ethernet frame"
+    channel.send(ethernet_frame)
+    frame = channel.receive()
+```
+
+The example requires an EoE-capable slave and a WinPcap-compatible Npcap
+installation on Windows (or the Linux packet-capture development package).
+
+SOEM is included under `vendor/SOEM` for development and is licensed separately. See its `LICENSE.md`.

soemx-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=68", "wheel", "Cython>=3.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soemx"
+version = "0.1.0"
+description = "Cython bindings for SOEM with EoE support"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "soemx contributors"}]
+dependencies = []
+
+[tool.setuptools]
+packages = ["soemx"]

soemx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soemx-0.1.0/setup.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+import os
+import sys
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+
+root = Path(__file__).parent.resolve()
+soem = root / "vendor" / "SOEM"
+sources = ["soemx/soemx.pyx", "soemx/soemx_native.c"]
+sources += [f"vendor/SOEM/src/{name}" for name in [
+    "ec_base.c", "ec_coe.c", "ec_config.c", "ec_dc.c", "ec_eoe.c",
+    "ec_foe.c", "ec_main.c", "ec_print.c", "ec_soe.c"]]
+if sys.platform == "win32":
+    platform_sources = [
+        "vendor/SOEM/osal/win32/osal.c",
+        "vendor/SOEM/oshw/win32/nicdrv.c",
+        "vendor/SOEM/oshw/win32/oshw.c",
+    ]
+    platform_includes = [
+        soem / "osal" / "win32",
+        soem / "oshw" / "win32",
+        soem / "oshw" / "win32" / "wpcap" / "Include",
+    ]
+    platform_libraries = ["wpcap", "Packet", "winmm", "ws2_32"]
+    platform_library_dirs = [soem / "oshw" / "win32" / "wpcap" / "Lib" / "x64"]
+elif sys.platform.startswith("linux"):
+    platform_sources = [
+        "vendor/SOEM/osal/linux/osal.c",
+        "vendor/SOEM/oshw/linux/nicdrv.c",
+        "vendor/SOEM/oshw/linux/oshw.c",
+    ]
+    platform_includes = [soem / "osal" / "linux", soem / "oshw" / "linux"]
+    platform_libraries = ["pcap", "pthread"]
+    platform_library_dirs = []
+else:
+    raise RuntimeError("soemx currently supports Windows and Linux builds")
+sources += platform_sources
+# setuptools requires source entries to be relative to setup.py.  The vendored
+# SOEM paths are normalized to POSIX separators for manifest generation.
+sources = [path.replace("\\", "/") for path in sources]
+
+extension = Extension(
+    "soemx._soemx",
+    sources=sources,
+    include_dirs=[str(soem / "include"), str(soem / "build" / "include"), str(soem / "osal"), *(str(path) for path in platform_includes), str(root / "soemx")],
+    library_dirs=[str(path) for path in platform_library_dirs],
+    libraries=platform_libraries,
+)
+
+extensions = cythonize([extension], language_level=3)
+for ext in extensions:
+    ext.sources = [os.path.relpath(source, root).replace("\\", "/")
+                   for source in ext.sources]
+
+setup(
+    ext_modules=extensions,
+    include_package_data=False,
+    exclude_package_data={"soemx": ["*.c", "*.h"]},
+)

soemx-0.1.0/soemx/__init__.py

@@ -0,0 +1,70 @@
+"""Python interface for SOEM, under active development."""
+
+from .errors import (SoemxError, SdoError, SdoInfoError, MailboxError,
+                     PacketError, ConfigMapError, EepromError, WkcError,
+                     NetworkInterfaceNotOpenError, Emergency)
+from .status import al_status_code_to_string
+from .adapters import Adapter
+
+NONE_STATE = 0x00
+INIT_STATE = 0x01
+PREOP_STATE = 0x02
+BOOT_STATE = 0x03
+SAFEOP_STATE = 0x04
+OP_STATE = 0x08
+STATE_ACK = 0x10
+STATE_ERROR = 0x10
+
+# Common EtherCAT register and CoE capability constants exposed by PySOEM.
+ECT_REG_WD_DIV = 0x0400
+ECT_REG_WD_TIME_PDI = 0x0410
+ECT_REG_WD_TIME_PROCESSDATA = 0x0420
+ECT_REG_SM0 = 0x0800
+ECT_REG_SM1 = ECT_REG_SM0 + 0x08
+ECT_COEDET_SDO = 0x01
+ECT_COEDET_SDOINFO = 0x02
+ECT_COEDET_PDOASSIGN = 0x04
+ECT_COEDET_PDOCONFIG = 0x08
+ECT_COEDET_UPLOAD = 0x10
+ECT_COEDET_SDOCA = 0x20
+
+__version__ = "0.1.0"
+
+
+def _load_native():
+    try:
+        from . import _soemx
+    except ImportError as exc:
+        raise RuntimeError(
+            "unable to load the soemx native extension; install Npcap "
+            "with WinPcap API-compatible mode on Windows"
+        ) from exc
+    return _soemx
+
+
+def __getattr__(name):
+    if name in ("Master", "find_adapters"):
+        native = _load_native()
+        return native.Master if name == "Master" else native.find_adapters
+    raise AttributeError(name)
+
+
+def open(interface: str, interface2=None):
+    """Open an EtherCAT master and optionally configure a redundant interface."""
+    Master = _load_native().Master
+    master = Master()
+    try:
+        master.open(interface, interface2)
+    except Exception:
+        master.close()
+        raise
+    return master
+
+__all__ = ["Master", "find_adapters", "open", "Adapter", "__version__", "al_status_code_to_string", "SoemxError", "SdoError", "SdoInfoError", "Emergency",
+           "MailboxError", "PacketError", "ConfigMapError", "EepromError",
+           "WkcError", "NetworkInterfaceNotOpenError", "NONE_STATE", "INIT_STATE",
+           "PREOP_STATE", "BOOT_STATE", "SAFEOP_STATE", "OP_STATE",
+           "STATE_ACK", "STATE_ERROR", "ECT_REG_WD_DIV", "ECT_REG_WD_TIME_PDI",
+           "ECT_REG_WD_TIME_PROCESSDATA", "ECT_REG_SM0", "ECT_REG_SM1",
+           "ECT_COEDET_SDO", "ECT_COEDET_SDOINFO", "ECT_COEDET_PDOASSIGN",
+           "ECT_COEDET_PDOCONFIG", "ECT_COEDET_UPLOAD", "ECT_COEDET_SDOCA"]

soemx-0.1.0/soemx/adapters.py

@@ -0,0 +1,18 @@
+"""Network adapter discovery helpers."""
+
+
+class Adapter:
+    """Description of a network adapter returned by :func:`find_adapters`."""
+
+    __slots__ = ("name", "desc")
+
+    def __init__(self, name, desc):
+        self.name = str(name)
+        self.desc = str(desc)
+
+    def __repr__(self):
+        return f"Adapter(name={self.name!r}, desc={self.desc!r})"
+
+
+def _decode(value: bytes) -> str:
+    return value.split(b"\0", 1)[0].decode("utf-8", errors="replace")

soemx-0.1.0/soemx/errors.py

@@ -0,0 +1,75 @@
+class SoemxError(Exception):
+    """Base class for soemx errors."""
+
+
+class SdoError(SoemxError):
+    def __init__(self, slave_pos=None, index=None, subindex=None,
+                 abort_code=None, desc=""):
+        self.slave_pos = slave_pos
+        self.index = index
+        self.subindex = subindex
+        self.abort_code = abort_code
+        self.desc = desc
+        super().__init__(desc)
+
+
+class SdoInfoError(SoemxError):
+    def __init__(self, message=""):
+        self.message = message
+        super().__init__(message)
+
+
+class MailboxError(SoemxError):
+    def __init__(self, slave_pos=None, error_code=None, desc=""):
+        self.slave_pos = slave_pos
+        self.error_code = error_code
+        self.desc = desc
+        super().__init__(desc)
+
+
+class PacketError(SoemxError):
+    def __init__(self, slave_pos=None, error_code=None, message="", desc=""):
+        self.slave_pos = slave_pos
+        self.error_code = error_code
+        self.message = message
+        self.desc = desc
+        super().__init__(message or desc)
+
+
+class ConfigMapError(SoemxError):
+    def __init__(self, error_list=None):
+        self.error_list = [] if error_list is None else list(error_list)
+        super().__init__(self.error_list)
+
+
+class EepromError(SoemxError):
+    def __init__(self, message=""):
+        self.message = message
+        super().__init__(message)
+
+
+class WkcError(SoemxError): pass
+class NetworkInterfaceNotOpenError(SoemxError): pass
+
+
+class Emergency(SoemxError):
+    """Emergency mailbox notification compatible with PySOEM."""
+
+    def __init__(self, slave, error_code, error_reg, b1=0, w1=0, w2=0):
+        self.slave_pos = slave
+        self.slave = slave
+        self.error_code = error_code
+        self.error_reg = error_reg
+        self.error_register = error_reg
+        self.b1 = b1
+        self.w1 = w1
+        self.w2 = w2
+
+    def __repr__(self):
+        return (f"Emergency(slave_pos={self.slave_pos}, error_code={self.error_code}, "
+                f"error_reg={self.error_reg})")
+
+    def __str__(self):
+        payload = bytes([self.b1]) + self.w1.to_bytes(2, "little") + self.w2.to_bytes(2, "little")
+        return (f"Slave {self.slave_pos}: {self.error_code:04x}, "
+                f"{self.error_reg:02x}, ({','.join(f'{x:02x}' for x in payload)})")