pysoem

1.1.13 verified Sat May 09 auth: no python

Cython wrapper for the SOEM (Simple Open EtherCAT Master) library. Provides Python bindings to control EtherCAT networks. Current version 1.1.13. Release cadence: irregular, several minor releases per year.

pip install pysoem

Common errors

error ModuleNotFoundError: No module named 'pysoem' ↓

cause Missing installation or wrong Python environment.

fix

Run 'pip install pysoem' in the correct virtual environment. Ensure pip is up to date.

error AttributeError: 'Master' object has no attribute 'config_init' ↓

cause Trying to use an older version of pysoem (pre-1.0) where the API was different, or a corrupted installation.

fix

Upgrade to the latest version: 'pip install --upgrade pysoem'. Check import path: from pysoem import Master.

error pysoem.slaves[0].sdo_read(0x1000, 1) -> OSError: SDO read failed ↓

cause Network issues, slave not responding, or incorrect SDO index/subindex.

fix

Verify network connection and slave state. Ensure master.state is 'OP'. Check that the slave supports the SDO.

Warnings

breaking In version 1.1.11, the default release_gil behavior changed. New functions and a global setting 'always_release_gil' were added. Code relying on GIL being held during SDO operations may need to explicitly set release_gil=False. ↓

fix Set pysoem.settings.always_release_gil = False if you need the GIL held for legacy reasons, or pass release_gil=False to individual calls.

gotcha The config_init() method may fail if called multiple times without a proper re-initialization. Bug fixed in 1.1.6, but still advisable to call config_init() only once per session. ↓

fix Ensure config_init() is called exactly once per master instance.

gotcha Properties 'config_func' and 'setup_func' can be None if not initialized. Accessing them before assignment can cause null pointer errors (fixed in 1.1.8). Always set them before use or check for None. ↓

fix Set config_func and setup_func on each slave before calling config_init(), or upgrade to 1.1.8+.

Imports

Master
```
from pysoem import Master
```
Primary class for EtherCAT master operations.
settings
```
from pysoem import settings
```
Module-level configuration object (e.g., timeouts, GIL behavior).
EMERGENCY
```
from pysoem import EMERGENCY
```
Emergency message type constant.

Quickstart

Basic EtherCAT master setup: open interface, configure slaves, map PDOs, set operational state.

import time
from pysoem import Master

master = Master()
master.open(os.environ.get('ETHERCAT_INTERFACE', 'eth0'))
master.config_init()

# Map PDOs (example)
for slave in master.slaves:
    print(slave.name)

master.config_map()
master.state = 'OP'
master.write_state()
master.receive_processdata()
time.sleep(0.1)

master.close()