PySOEM is a Cython wrapper for the Simple Open EtherCAT Master Library (SOEM) that enables basic system testing of EtherCAT slave devices. Key capabilities include:

• Process Data: Reading input process data and writing output process data.
• SDO: Service Data Object (SDO) read and write operations.
• EEPROM: Reading and writing to the slave's EEPROM.
• FoE: File over EtherCAT (FoE) read and write operations.

Warning: Real-time applications using PySOEM may require special considerations regarding timing and execution.

Once you have obtained a device reference from the master.slaves list, you can interact with the EtherCAT slave. The device reference provides access to:

• Device Metadata: Such as device.name, which is populated during the master.config_init() phase.
• CoE (CANopen over EtherCAT) Objects: Ability to read and write CoE objects.
• Process Data: Ability to read input process data and write output process data.

PySOEM provides mechanisms to manage the Global Interpreter Lock (GIL) and low-level timeouts to improve performance and control.

No-GIL Support

You can control whether PySOEM releases the GIL using three methods:

1. Global setting: pysoem.settings.always_release_gil
2. Master instance attribute: master.always_release_gil
3. Function argument: Passing release_gil=True to specific functions (e.g., sdo_read() or send_overlap_processdata()).

Timeout Configuration

You can configure low-level timeouts at run-time using pysoem.settings.timeouts.

To perform a basic scan of an EtherCAT network and print the names of all discovered slave devices, initialize a pysoem.Master instance, open it using your network adapter's ID, and call config_init(). If config_init() returns a value greater than 0, you can iterate through the master.slaves list to access device information.

import pysoem

master = pysoem.Master()

# Replace 'Your network adapters ID' with your actual interface ID
master.open('Your network adapters ID')

if master.config_init() > 0:
    for device in master.slaves:
        print(f'Found Device {device.name}')
else:
    print('no device found')

master.close()

The ctypes module provides a flexible way to handle various CoE types, including floats and booleans.

To read a value, use ctypes.<type>.from_buffer_copy(bytes_data).value. To write a value, wrap the value in a ctypes type and convert it to bytes using the bytes() constructor.

Warning: The ctypes approach for writing is dependent on the machine's endianness, as byteorder cannot be explicitly specified like with int.to_bytes.

import ctypes

# Reading a 32-bit unsigned integer
vendor_id = ctypes.c_uint32.from_buffer_copy(device.sdo_read(0x1018, 1)).value

# Writing a 32-bit unsigned integer
device.sdo_write(0x3456, 0, bytes(ctypes.c_uint32(1)))

To use PySOEM on Windows, ensure the following are installed:

• Python 3 (64-bit)
• Packet Capture Driver: You must install either Npcap or WinPcap.

Important for Npcap users: During the Npcap installation process, you must check the option "Install Npcap in WinPcap API-compatible Mode" for PySOEM to function correctly.

To use PySOEM on Linux, ensure the following are installed and configured:

• Python 3: The runtime environment.
• GCC: Required because PySOEM is compiled during the installation process.
• Privileges: Python scripts that utilize PySOEM must be executed with administrator privileges (e.g., using sudo) to interact with the network interface.

If you choose to run your Python scripts with sudo (not recommended as a best practice), you must forward your PATH environment variable. If you do not, the system may fail to find your Python interpreter.

To run a script with root access while preserving the PATH:

sudo env "PATH=$PATH" python <your-pysoem-python-script>

When running complex tools like tox, you may need to forward additional environment variables such as PYENV_ROOT and PYTHONPATH to ensure the environment is correctly reconstructed.

Many PySOEM tasks (such as running tests or examples) require hardware access via a specific network interface. You must specify the adapter ID using the IFACE variable. You can do this in three ways:

1. Inline with make: Pass it as an argument to a make command: make <target> IFACE=<adapter-id>.
2. Environment Variable: Set a system environment variable named IFACE.
3. .env file: Create a .env file in the project root with the following format:

IFACE=<adapter-id>

Linux restricts raw Ethernet communications, which PySOEM requires. You can grant the Python interpreter the necessary permissions using the CAP_NET_RAW capability without running the entire process as root. This allows python3 to execute PySOEM scripts successfully.

To enable the capability:

sudo setcap cap_net_raw+ep /usr/bin/python3

Note: To remove this capability later, you can use setcap to clear the permissions (though the provided documentation shows the same command used for enabling, typically you would use sudo setcap '' /usr/bin/python3 to clear it).

You can install PySOEM using standard Python package managers. It is recommended to use a virtualenv to manage your dependencies.

python -m pip install pysoem

or

pip install pysoem