Datenschutzerklärung (Privacy; Legal information in German)

Userspace EtherCAT master

This is a userspace port of the IgH EtherCAT-Master for Linux. Running in userspace avoids any kernel dependencies or patched kernel drivers.

Depending on system capabilities, it can reliably support cycle frequencies of 500 Hz or more. For very high frequencies, the original kernel master, usually in combination with a hard-real-time environment, is still necessary.

Porting to systems other than Linux should be easier starting from this port than from the original kernel code, but might still require some effort. E.g., the code uses Linux's tap devices, which might not be available on other systems, to provide virtual network interfaces for Ethernet-over-EtherCAT (EoE).

To find out how to use it, see Usage.

Installation

Binaries

Binaries for Debian bookworm on amd64 are provided. For other systems, you have to build things yourself from sources. Even on the given system, you might want to do so, to have more flexibility. The package does not have many build dependencies.

According to Debian policy, the following binary packages are built. After downloading, you can install them with sudo dpkg -i FILENAME.

libethercat-userspace1_1.5.0-7_amd64.deb
The actual library. You need this package if you want to use the userspace EtherCAT master at all.
libethercat-userspace-dev_1.5.0-7_amd64.deb
The development files (e.g. headers). You need this package if you want to compile programs that use the userspace master, i.e. unless you only download binaries that do so.
libethercat-userspace1-dbgsym_1.5.0-7_amd64.deb
The debugging symbols. You need this package if you want to debug errors in the userspace master (not in a program that uses it), unless you compile the master yourself in the first place.
ethercat-userspace_1.5.0-7_amd64.deb
The command-line "ethercat" tool and a dummy master. You do not need this package to build userspace EtherCAT applications, but it can be useful for simple access to the EtherCAT bus, for debugging EtherCAT problems and for support scripts.
ethercat-userspace-dbgsym_1.5.0-7_amd64.deb
The debugging symbols for the command-line tools. You need this package if you want to debug errors in those tools.

Building from sources on Debian and compatible systems

If your system uses deb packages (e.g. Debian, Ubuntu), you can download the following sources. As usual for deb packages, they consist of three files:

To build them, go to the directory where you downloaded them and do:

dpkg-source -x ethercat-userspace_1.5.0-7.dsc

cd ethercat-userspace-1.5.0

dpkg-checkbuilddeps

If this command reports any missing build dependencies, install them via apt-get or your usual package installation method, then rerun the command until it does not report anything.

The following command does the actual building. You can vary the number after -j to select the number of parallel processes. A rule of thumb is to use slightly more than the number of cores your CPU has. On small machines, you can omit the -j4 option entirely. (Note: Unless with make, you cannot use -j without a number for unlimited parallelism, but you can use a large number if you have a fast machine with plenty of memory.)

debuild -us -uc -j4

If this command completes successfully, you will find in the parent directory the newly built .deb files which should be the same (possibly apart from the architecture name) as listed under Binaries. You can install any or all of them as described there.

Building from sources on other systems

Besides standard tools such as tar, you need the following prerequisites. Make sure you have installed them before you proceed:

automake, autoconf, make, quilt, help2man, gcc, g++

(You can avoid quilt by applying the patches manually in the correct order, and help2man by editing the respective Makefile.am files to avoid generating man pages. But these tools should be easy to install and can be useful in other situations, so it is recommended to install them.)

Download the following files:

Go to the directory where you downloaded them and do the following steps. As usual, you can give various options to configure, and you can vary the -j option to make as discussed under Building from sources on Debian and compatible systems. You can also use the DESTDIR mechanism to install files in a different location, e.g. to build binary packages:

tar xjf ethercat-userspace_1.5.0.orig.tar.bz2

cd ethercat-1.5.0

tar xJf ../ethercat-userspace_1.5.0-7.debian.tar.xz

QUILT_PATCHES=debian/patches quilt push -a

autoreconf

./configure --prefix=/usr/local

make -j4

sudo make install

Usage

To use the userspace master, you should be familiar with the original IgH kernel master. In case of doubt, refer to its documentation.

Command-line tool

The ethercat tool works just like it does with the kernel master.

Additionally, it has a new option --host to access an ethercat master on a remote host. It defaults to the local host.

Dummy master

The program ethercat_master is a dummy master without an application task. Running this dummy master is equivalent to, with the kernel master, loading the master module and no application module.

You need this if you do not have an application yet, or do not want to start it yet, but want access to the EtherCAT bus, e.g. via the ethercat tool.

Compiling with the userspace master

The userspace master code is provided as a library libethercat_master that can be linked into an executable with application code.

It is recommended to use pkg-config if your build system supports it. Otherwise use the following compiler options manually:

For compiling (important!):
pkg-config --cflags libethercat_master
or manually:
-fno-strict-aliasing -DEC_MASTER_IN_USERSPACE
For linking:
pkg-config --libs libethercat_master
or manually:
-lethercat_master -lpthread

Programming

The programming interface is mostly the same as for the kernel master. There are two new functions you need to use:

int ecrt_init(unsigned int master_count_, const char *const *master_macs, unsigned int backup_count_, const char *const *backup_macs, unsigned int debug_level_);
You must call this function before any other EtherCAT functions. The parameters correspond to the module arguments for the kernel master, i.e. the master and backup MAC addresses and the debug level. In the simplest case, you need to give one master MAC address, no backups, and a debug level of 0.
It returs 0 in case of success, and a negative error number otherwise.
void ecrt_done(void);
You should call this function before your program terminates to clean up properly.
Note: Proper cleanup is not nearly as critical in userspace as it is in kernel code, since when the program terminates, the operating system will close all sockets and release all memory anyway. Still, it is good practice to clean up properly. Besides, you might need some application-level cleanup, anyway.

The dummy master ethercat_master.c can serve as an example for their use. Note that most of its code is actually for (primitive) command-line argument handling and for catching termination signals.

Environment

Userspace EtherCAT applications, including the dummy master, generally require root privileges in order to access the master, and possibly backup, devices by raw ethernet sockets, and to open tap devices for EoE.

For realtime applications, you usually want to use a soft-realtime scheduler for the cyclic task, sometimes also for other tasks with slightly lower priority. The library does not do this, it is up to you to do so in your code, see sched_setscheduler or pthread_setschedparam.

You might also want to employ CPU affinity, e.g. taskset to bind all realtime processes to one CPU core and /proc/irq/*/smp_affinity to bind the IRQ(s) of the EtherCAT network interface to the same core or a second core, and bind all other processes in the system and possibly other IRQs to the remaining cores. In some tests, this did help to avoid occasional packet loss caused by burst activity of other processes.

For even better realtime response, you might want to use a kernel compiled with RT_PREEMPT.

Contact

You can contact me at nospam-f.heckenbach-dontspam(at)fh-soft.de. For spam protection, please remove the obvious parts, and note that my mail server employs greylisting.

For general EtherCAT questions not related to the userspace port, please use the mailing lists for the original IgH EtherCAT-Master.