Compatibility with kernel 5.xx

This page is mostly copy/paste from the Installation page but accounts for some variations necessary to compile a real-time Linux kernel under version 5.xx, and to run the EtherCAT Master under the same version. Please note that since RT features are required for this application, it is not recommended to run Linux on a virtual machine.

Install Linux OS

1. Download Ubuntu 20.04.1 LTS image from here
2. Create a bootable USB stick (for instance using Rufus for Windows)
3. Install the operating system alongside Microsoft Windows (it is necessary because the majority of drive systems has to be set up in a Windows-based environment)
4. Download all the necessary updates during installation (better having wired ethernet connection)

Once Ubuntu is up and running, a real-time kernel must be installed.

Install real-time kernel

Some kernel versions cannot be installed, if you are running ubuntu 20.xx. For example, with Ubuntu 20.04.1 LTS only 5.xx kernels can be used. One of the latest stable releases of the RT kernel is the 5.10.120, which is employed here. To obtain it, follow the instructions below:

1. Download linux-5.10.120.tar.xz here;
2. Download the real-time patch patch-5.10.120-rt70.patch.xz here and download patch-5.4.84-rt47.patch.xz (it may be in older folder);
3. Open a terminal and execute the following commands:

cd Downloads
tar xf linux-5.10.120.tar.xz
cd linux-5.10.120
xzcat ../patch-5.10.120-rt70.patch.xz | patch -p1
cp /boot/config-$(uname -r) .config
sudo apt install flex bison
sudo apt-get install libncurses-dev libssl-dev libelf-dev
yes "" | make oldconfig
make menuconfig

In the DOS-style window, you are prompted to, use the keyboard to navigate to General setup -> Preemption Model and select Fully Preemptible Kernel (RT). Then save and exit.

Next, conclude the installation by compiling the kernel as follows (it will take some minutes):

make modules -j$(nproc)
make -j$(nproc)
sudo make modules_install
sudo make install
cd /lib/modules/5.10.120
sudo find . -name *.ko -exec strip --strip-unneeded {} +
sudo gedit /etc/initramfs-tools/initramfs.conf

at this stage, a document is opened (if you don't like gedit, please use any other text editor). You need to find the line COMPRESS=lz4 and modify it with COMPRESS=xz. This is needed in order to shrink the huge initramfs image of RT kernel 5.xx, and consequently to avoid kernel panic at boot (many, many, MANY thanks to Aiden Yeomin Nam comment here).

Then you can finish your installation with:

sudo update-initramfs -u
sudo update-grub

Now you should be able to boot with the newly installed real-time kernel by using the advanced option in the grub at start-up. As far as the user is concerned, some minor lagging in the monitor might be experienced but it is normal. To test the kernel and getting an idea of how a real-time application is set up, https://wiki.linuxfoundation.org/realtime/start can be consulted.

Install EtherCAT Master

To set up an EtherCAT Master application, please open a terminal and follow the instructions below. Depending on your target system, you'll need to clone a different branch of the etherlab repository. As a rule of thumb, if you are using a desktop PC with an Intel processor, you should have an Intel network card available, whereas if you are using a modern laptop, Realtek network cards are more common. Anyway, open a terminal to find out

sudo lshw -class network

and see if your network interface is using e1000e or r8169 driver. In the first case, you need to clone this repository, otherwise this one.

Unzip it, and enter the directory. Locally open a terminal and type:

apt-get install dh-autoreconf
./bootstrap

and depending on your network driver

./configure --disable-8139too --enable-generic --enable-e1000e --disable-eoe --prefix=/opt/etherlab

or

./configure --disable-8139too --enable-generic --enable-r8169 --disable-eoe --prefix=/opt/etherlab

Now you can proceed to the build step. In the same terminal, type:

make modules -j$(nproc)
make -j$(nproc)
make modules_install
make install

Now the ethercat master is installed in ”/opt/etherlab” and has to be configured at application level. Therefore:

cd /opt/etherlab/
mkdir /etc/sysconfig
cp etc/sysconfig/ethercat /etc/sysconfig/
ln -s /opt/etherlab/etc/init.d/ethercat /etc/init.d/ethercat
chmod +x /etc/init.d/ethercat
systemctl enable ethercat

The "systemctl enable" command should start the ethercat process at every kernel boot, but it is a recent feature of kernel 5.xx and may not work all the time (meaning, I have not figured it out yet ;), please let me know if you do!). Now you have to find the serial of the ethernet port you are going to attach your ethercat devices. To do so, on a different terminal, type lshw -class network and note down the serial under the group described as Ethernet interface. Then, in the original terminal, open "/etc/sysconfig/ethercat" (for instance with gedit) and edit it with the previously noted information:

MASTER0_DEVICE="$(YOUR_PCI_SERIAL)"
DEVICE_MODULES="e1000e"

or

MASTER0_DEVICE="$(YOUR_PCI_SERIAL)"
DEVICE_MODULES="r8169"

Now we are good to go and we can test if the master can work properly with:

/etc/init.d/ethercat start

You should see the following line printed on the console:

Starting EtherCAT master 1.5.2 done

Additional commmand line tools can be installed by creating the following link:

ln -s /opt/etherlab/bin/ethercat /usr/local/bin/ethercat

At this point, if you reboot the PC, at the startup of the real-time kernel the EtherCAT master will be automatically loaded, so that it can be used right away by any application.