Build IgH EtherCat Master on BBB/RPi

EtherCat

The IgH EtherCAT Master can be built from source on single-board computers such as the BeagleBone Black (BBB) or Raspberry Pi (RPi), as well as on a standard PC. The EtherCAT master uses the Ethernet interface wired via 100-BaseT to the EtherCAT slaves. Because EtherCAT is a real-time communication bus, the Ethernet interface should not be interefered with other traffic. An additional shell connection to the target - such as WLAN or UART - is required to log in, install, build, and configure all necessary components. A realtime kernel is not necessary but will operate EtherCat on time critical tasks like servo motor control.

Install Linux Distro

BBB

Use one of the latest distros from here and write it to a SD-card. After reinserting the card into the BeagleBone Black and power on, the Debian distro starts. Login as user debian with default password and install needed tools for building on target:

sudo apt-get update
sudo apt-get install dkms autoconf autoconf-archive automake pkg-config pkgconf pkgconf-bin libpkgconf3 libtool zstd autotools-dev wpasupplicant

The latest kernel which is needed for realtime must be installed (at time of writing):

sudo apt update && sudo apt install linux-image-6.12.57-bone-rt-r40 linux-headers-6.12.57-bone-rt-r40

Other kernels can be uninstalled. After restarting and login again, check whether kernel is realtime capable with uname -a:

Linux BeagleBone 6.12.57-bone-rt-r40 #1 PREEMPT_RT Wed Nov 19 04:58:21 UTC 2025 armv7l GNU/Linux

Network adapter

The BBB has one Ethernet connector which must exclusively used for EtherCat. To connect a shell to the BBB, a serial connection to J1 with minicom to /dev/ttyUSB0 can be used or a more comfortable a wifi USB adapter as second network connector. This adapter doesn't need to be a fast one - an old one found in the tinkering box is sufficient.

Installations

For the USB adapter to work look for the appropriate firmware in Linux, e.g. for a Ralink RT2870:

apt-get install firmware-mediatek

Install WPA supplicant for connecting with password to a wifi and purge not needed ifupdown:

apt get install wpasupplicant
apt get purge ifupdown
systemd-networkd

Create a file /etc/systemd/network/30-wlan.network with following content:

[Match]
Name=wlan0
Type=wlan
WLANInterfaceType=station

[Network]
DHCP=yes

[DHCP]
UseDNS=yes
wpa-supplicant

Create a configuration file /etc/wpa_supplicant/wpa_supplicant-wlan0.conf for the WPA-supplicant:

ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev
update_config=1

# Add SSID and password for the desired wifi access point to connect to
network={
       ssid="myssid"
       psk="myssid_password"
}

Enable the service for the name of the configuration file:

sudo systemctl enable --now wpa_supplicant@wlan0.service

Enable and start the network service:

sudo systemctl enable --now systemd-networkd

RPi 3B

Use the latest Raspberry Pi OS from here and write it to a SD-card. After inserting and booting the RPi, a PREEMPTRT patched arm64 kernel should be installed by default. Check with a uname -a.

Get and configure IgH EtherCat NO

Fetch IgH EtherCat sources to the target and configure.

  • call configure --with-linux-dir optionally: should point to the kernel sources installed before, otherwise omit argument
git clone https://gitlab.com/etherlab.org/ethercat.git
cd ethercat
git checkout stable-1.6
echo "AUTOMAKE_OPTIONS = subdir-objects" >> tool/Makefile.am
./bootstrap
./configure --enable-generic --disable-8139too

Build and install EtherCat kernel modules

First a kernel module build from the unneeded examples must be removed, then kernel module build can be started:

sed -i '\/obj-m := mini\//d' ./examples/Kbuild.in
make modules && sudo make modules_install && sudo depmod

Building kernel modules on a BBB/RPi takes some time.

BBB

Copy the actual kernel config to the kernel modules directory:

zcat /proc/config.gz | sudo tee /lib/modules/6.12.57-bone-rt-r40/build/.config > /dev/null

Download the kernel modules of etherlab ethercat and build and install Kernel modules with dkms:

curl -sL https://download.opensuse.org/repositories/science:/EtherLab/Debian_13/all/ethercat-dkms_1.6.8.g2543cc5-1+27.3_all.deb | sudo tee /tmp/pkg.deb >/dev/null && sudo dpkg -i /tmp/pkg.deb && sudo apt-get -f -y install
curl -sL https://download.opensuse.org/repositories/science:/EtherLab/Debian_13/armhf/ethercat-master_1.6.8.g2543cc5-1+27.3_armhf.deb | sudo tee /tmp/pkg.deb >/dev/null && sudo dpkg -i /tmp/pkg.deb && sudo apt-get -f -y install

The file /etc/ethercat.conf needs to be edited to associate the correct ethernet adapter to the EtherCat master:

MASTER0_DEVICE="eth0"
DEVICE_MODULES="generic"

The EtherCat master module must be enabled:

sudo systemctl enable ethercat.service

After a reboot it must be checked whether the ethercat.service is running, the modules ec_master, ec_generic and the device /dev/EtherCat0 are created.

RPi

https://download.opensuse.org/repositories/science:/EtherLab/Debian_13/arm64/ethercat-master_1.6.8.g2543cc5-1+27.3_arm64.deb

Build and install EtherCat libs

If you just want to build and install the EtherCat-libraries without kernel modules and examples, cd into ~/ethercat/lib/ and call make all. This also generates a EtherCATConfig.cmake which can be found by cmake find_package. For installing the includes, cd into ~/ethercat/include/ and call sudo make install.

cd ./lib
make all && sudo make install
cd ../include
sudo make install

The libraries are installed per default into /usr/local/lib. In case of building your own project dependent on the EtherCat libraries, the libraries path must be assigned to CMAKE_PREFIX_PATH when invoking cmake from the project.

<project dir> cmake .. -DCMAKE_PREFIX_PATH=/usr/local/lib

Build and install EtherCat tools

Build tools (ethercat-CLI) and install:

cd tool
make all
sudo make install

Cross build on a host

Alternatively build source cross compile against a kernel source in /home/debian/linux and install modules to mounted kernel directory on the the SBC:

debian@pc:~/$ mkdir piroot
debian@pc:~/$ sshfs root@pi:/ ~/piroot
debian@pc:~/$ cd ethercat
debian@pc:~/ethercat$ ./bootstrap
debian@pc:~/ethercat$ ./configure --with-linux-dir=/home/debian/linux --enable-generic --disable-8139too --host arm-linux-gnueabihf CFLAGS='-g -O0' CXXFLAGS='-g -O0'
debian@pc:~/ethercat$ export ARCH=arm
debian@pc:~/ethercat$ export CROSS_COMPILE=/usr/bin/arm-linux-gnueabihf-
debian@pc:~/ethercat$ export INSTALL_MOD_PATH=~/piroot
debian@pc:~/ethercat$ make all modules
debian@pc:~/ethercat$ make doc
debian@pc:~/ethercat$ make modules_install

Setup IgH EtherCat

udev

The following rule ensures that the device /dev/EtherCAT0 is owned by the non-root user debian instead of user root. This is needed because we want a non-root user to drive EtherCat slaves via the master. Create a file /etc/udev/rules.d/99-ethercat-device-ownership.rules with following content:

KERNEL =="EtherCAT[0-9]*" , SUBSYSTEM=="EtherCAT", MODE ="0664", OWNER="debian", GROUP ="debian"

Reload the rules to take effect:

sudo udevadm control --reload-rules

Copy and edit /usr/local/etc/ethercat.conf. Use the MAC address of your eth0 device.

MASTER0_DEVICE="78:a5:04:c8:9e:12"
DEVICE_MODULES="generic"
LINK_DEVICES="eth0"

Set up ethercat NIC:

sudo ip link set eth0 up

The link can be set up permanently also by configuring the interface in /etc/network/interfaces.

iface eth0 inet manual
up ip link set eth0 up

Start ethercat service which generates the device file /dev/EtherCAT0:

sudo ethercatctl start

Test

First lets see, if device is created:

debian@SBC:~$ ls -la /dev/EtherCAT0
crw------- 1 root root 239, 0 13. Jan 12:01 /dev/EtherCAT0

Check master running:

debian@SBC:~$ sudo ethercat master
Master0
  Phase: Operation
  Active: yes
  Slaves: 0
  Ethernet devices:
    Main: b8:27:eb:0b:6e:ac (attached)
      Link: UP
      Tx frames:   699298
      Tx bytes:    41957880
      Rx frames:   0
      Rx bytes:    0
      Tx errors:   0
      Tx frame rate [1/s]:    200    268    434
      Tx rate [KByte/s]:     11.7   15.7   25.4
      Rx frame rate [1/s]:      0      0      0
      Rx rate [KByte/s]:      0.0    0.0    0.0
    Common:
      Tx frames:   699298
      Tx bytes:    41957880
      Rx frames:   0
      Rx bytes:    0
      Lost frames: 699298
      Tx frame rate [1/s]:    200    268    434
      Tx rate [KByte/s]:     11.7   15.7   25.4
      Rx frame rate [1/s]:      0      0      0
      Rx rate [KByte/s]:      0.0    0.0    0.0
      Loss rate [1/s]:        200    268    434
      Frame loss [%]:       100.0  100.0  100.0
  Distributed clocks:
    Reference clock:   None
    DC reference time: 0
    Application time:  0
                       2000-01-01 00:00:00.000000000

Detect slaves:

debian@SBC:~$ sudo ethercat slaves --verbose

Read SDO 0x6061 from slave alias 1001:

debian@SBC:~$ sudo ethercat upload -a1001 0x6061 0x0 --type int8

Previous Post