EtherLab Installation
EtherLab setup
Contents
Introduction
EtherLab is an open source toolkit for rapid real time code generation under Linux. It enables compiling MATLAB/Simulink models and running on a real time Linux system. Given that the computer an Ethernet port available, the computer can become a master device for several slaves using the EtherCAT communication protocol. This manual gives step-by-step instruction on how to set up a real time control framework using EtherCAT master-slave communication. The hardware setup used for this manual consists of an Intel mini PC that will be configured as EtherCAT master device. The EtherCAT slave devices that will be connected to the master are a coupler, analogue input and junction from Beckhoff and two motor controllers from ELMO (type Gold Solo Whistle).The slaves are connected as shown in the figure. Specifications of all these devices can be found in Appendix A . This manual gives installation instruction for the following software components:
- OpenSUSE 13.1 x64
- Kernel 3.4.32_rt46-2.1 for real time running
- MATLAB 2014 x64
- EtherLab 2.1.0. including MATLAB integration
- IgH EtherCAT Master 1.5.2
- Pdserv 1.1.0
Next, some instructions will be provided for creating, building and running MATLAB/Simulink models for built-in and generic hardware. The text in a solid boxes (as shown below) are commands that have to be entered in the terminal.
some text
Installing Linux
OpenSUSE USB Install
The Linux distribution used for this set up is OpenSUSE 13.1 x64. The following installation steps are recommended:
- Download the 13.1 distribution from [OpenSuse Distributions]
- Create a Live USB installation by following one of the instructions for Windows or Linux using the openSUSE-13.1-KDE-Live-x86_64.iso image.
- Before installation, check the BIOS setting of the computer. and follow the instructions [HERE]
- Use the following options during installation:
- choose installation from boot menu
- language: English, agree license
- time zone
- username + password
- disable automatic login?
- reboot
- automatic configuration (just wait)
- Use the following partitioning setup (the device numbering and order is arbitrary):
- With the new NUC(nuc5i3ryh), the error below is not ocurring. if the error does popup, follow the following step. After the installation, the BIOS of the NUC (and some other computers) might not be able to boot OpenSUSE. The solution for this problem is described here. In short, the problem was solved by running the linux terminal from a Live USB pen and entering the following code:
sudo mount /dev/sda2 /mnt sudo mkdir /mnt/EFI/BOOT sudo cp /mnt/EFI/OpenSUSE/* /mnt/EFI/BOOT sudo mv /mnt/EFI/BOOT/grubx64.efi /mnt/EFI/BOOT/bootx64.efi/
- For those who are new to OpenSUSE, some tips specific to this OS described in Appendix B .
- This manual assumes that an internet connection is available, so set it up.
Now, boot the OpenSUSE and log-in. If for some reason, you can start up OpenSUSE in recovery mode, but not in normal mode(the same for the rt_preempt kernel). It could be the graphic card driver compatibility issue. It only affects the splash screen. Try the following steps(edit the startup parameter settings)
- Highlight the kernel that you cannot startup with;
- type 'e' on the keyboard to edit the parameters;
- at the end of the line started with "kernel", add nomodeset
This could possibly solve the problem of halting in the splash screen in normal mode. See Ref1 and Ref2 for explanations.
Installing Real Time kernel
For OpenSuse 13.2, the steps are:
- Go to http://software.opensuse.org/package/kernel-preempt_rt
- Choose OpenSuse13.1, then 'show unstable packages'
- Choose 1-Click intall for package home:repabuild:preempt
- Do the same for kernel-preempt_rt-headers
- Do the same for kernel-preempt_rt-firmware
Once the packages are installed, restart the system. When rebooting the system, select “OpenSUSE 13.1, with Linux 3.4.32-rt46-2-preempt” in the boot loader (grub2) under “advanced functions for OpenSUSE 13.1”. To double check that the proper kernel is loaded, type:
uname -r
this should return: 3.4.32_rt46-2-preempt-rt, which means the real-time kernel is operational. Note that all following installation steps should be performed with this kernel active.
For OpenSuse 13.2 the steps are slightly different:
- Go to http://software.opensuse.org/package/kernel-preempt_rt
- Choose OpenSuse13.1, then 'show unstable packages'
- Choose 1-Click intall for package home:repabuild:preempt
- after the package is installed, restart the system, and select the rt-preempt kernel
- after startup, go to software packages and search for "preempt"(very likely you have 3 hits and one is the install rt-preempt kernel), install the other two packages.
The last step is done to obtain the source files, so that Etherlab can patch it later.
Using EtherCat without Real Time kernel
Ethercat Master also seems to run with a non-realtime kernel. This may be convenient if you want to run it as a virtual machine. In order to work, you can skip the step of installing the real time kernel, but you do need to make sure you have the source of the currently active kernel on the pc. For that, find the version of the current kernel by typing uname -r. It should give something like 3.16.6-2-desktop. Then, get the sources by typing (change version number if necessary):
sudo zypper -n install kernel-desktop-devel=3.16.6-2
Master Software
Prerequisites
To install to software as described in the next sections, the following packages should installed from the repository (prerequisites). You can do this by going to "Install / remove software" after clicking the 'start' button:
- java-1_7_0-openjdk - Java runtime environment based on OpenJDK 7 and IcedTea 7
- cmake - Cross-platform, open-source make system
- autoconf - A GNU Tool for Automatically Configuring Source Code
- automake - A Program for Automatically Generating GNU-Style Makefile.in Files
- gcc - The system GNU C Compiler
- gcc-c++ - The system GNU C++ Compiler
- log4cplus-devel - Development files for log4cplus
- commoncpp2-devel - Files for developing CommonC++ applications
- libyaml-devel - Development files for libyaml
- libX11-devel - Development files for the Core X11 protocol library
- fftw3-devel - Include Files and Libraries mandatory for Development
- fltk-devel - Include Files and Libraries mandatory for Development
- doxygen
Alternatively, you can install all packages at once from the command line by typing (one command which is divided over two lines):
sudo zypper -n install java-1_7_0-openjdk cmake autoconf automake gcc gcc-c++ log4cplus-devel \ commoncpp2-devel libyaml-devel libX11-devel fftw3-devel fltk-devel doxygen
Installing MATLAB 2014B x64
Make an installation folder with the proper permissions:
cd /usr/local/ sudo mkdir ./MATLAB sudo chown <username>:users /usr/local/MATLAB/
The <username> label refers to your Linux login user name
Download the installer for the 64 bit version of MATLAB 2014b from the [Mathworks webpage] using a MathWorks account. Put the zip file in the “Downloads” directory. Unzip and start the installer by:
cd ~/Downloads/ unzip matlab_R2014b_glnxa64.zip -d ./matlab_R2014b_glnxa64 cd ./matlab_R2014b_glnxa64/ ./install
Now, follow the installation wizard. Make sure the installation folder is set to “/usr/local/MATLAB/”. After successfully finishing the installation and activating make a symbolic link to the MATLAB executable:
sudo ln -s /usr/local/MATLAB/R2014b/bin/matlab /usr/local/bin/<
Just the “matlab” command will start a Matlab session from the terminal. Some tips and tricks to set-up maltab correctly are described in Appendix D
Installing EtherLab 2.1.0
First, set up the installation directory and permissions for etherlab
cd /usr/local/ sudo mkdir etherlab sudo chown <username>:users ./etherlab/ sudo chmod 775 ./etherlab/ cd ./etherlab mkdir src cd ./src
Now, download and extract the etherlab tar files:
cd /usr/local/etherlab/src wget http://www.etherlab.org/download/etherlab/etherlab-2.1.0.tar.bz2 tar xjf etherlab-2.1.0.tar.bz2
Proceed with the installation:
mkdir etherlab-2.1.0-build cd etherlab-2.1.0-build/ cmake -DPREFIX=/usr/local/etherlab ../etherlab-2.1.0 make make install
Be careful when entering the DPREFIX parameter! The path name should not end with a slash. The version of etherlab contains a c-file (ec_slave3.c) that is not compatible with the newer MATALB versions. The problem is discussed [here]. The solution is:
cd /usr/local/etherlab/rtw/blocks/EtherCAT/ wget https://symbitron.eu/wiki/images/b/b6/Ecslave.c mv ec_slave3.c ec_slave3.c.bak mv Ecslave.c ec_slave3.c
original file location was: http://lists.etherlab.org/pipermail/etherlab-users/attachments/20140402/cf83e324/attachment.c
Now, set the permissions to MATLAB search paths:
sudo chown <user>:users /usr/local/MATLAB/R2014b/toolbox/local/pathdef.m sudo chmod 664 /usr/local/MATLAB/R2014b/toolbox/local/pathdef.m
Continue the installation in the command line inside MATAB:
matlab>> cd /usr/local/etherlab/rtw/ matlab>> setup_etherlab
There will be some warnings about the gcc version. They can be ignored. Close MATLAB.
Installing the IgH EtherCAT master 1.5.2
Download the ethercat master source files:
cd /usr/local/etherlab/src wget http://www.etherlab.org/download/ethercat/ethercat-1.5.2.tar.bz2 tar xjf ethercat-1.5.2.tar.bz2
The next part is hardware specific, so before continuing to the installation, the driver of the Ethernet port of the system should be known. The driver can be found in the network manager as shown in the figure below: 
We do not know how to get this fancy window, but the Network-Manager is enabled by typing '/sbin/yast2' in the terminal, choose 'network setting', 'global options' and under 'Network Setup Method' choose 'User Controlled with NetworkManager'. If you now type 'nm-tool' in the terminal, we will get a printout as in the image.
Alternatively, instead of trying to get the graphical display shown above, you can run
sudo lspci -v | grep "Ethernet\|driver"|grep -A1 Ethernet
(or just sudo lspci -v and look for the 'Ethernet Controller' sections manually.
This system is running an e1000e driver. Other supported drivers are 8139too, e100, e1000, r8169. If your driver is not in the list, use the generic* driver. In the next commands, make sure that the proper driver is selected (use: --enable-<driver> and --disable-<driver>)** :
*The availability of EtherCAT drivers also depend on the kernel version. For more info can be found [here]
**By default, the 8139too and generic drivers are enabled
cd ./ethercat-1.5.2/ ./configure --prefix=/usr/local/etherlab --disable-8139too --enable-e1000e make make modules make doc sudo make install sudo make modules_install sudo /sbin/depmod
We got the follwoing error:
depmod: ERROR: Module 'hci_vhci' has devname (vhci) but lacks major and minor information. Ignoring.
It has something to do with bluetooth so we ignored it.
if OpenSuse 13.2 is used, replace the second line with( this assumes to use the generic ethernet card driver)
./configure --prefix=/usr/local/etherlab --disable-8139too
Make a symbolic link to the ethercat master:
sudo ln -s /usr/local/etherlab/bin/ethercat /usr/local/bin/
The EtherCAT Master should be run as a service. There are two ways to start services in Linux the systemd and SysVInit. In openSUSE, the systemd is implemented (although SysVInit is supported) and will be used.
First, edit the configuration file:
*using nano because kwrite won't run with sudo. Exit nano by pressing Control-X, then Y
cd /usr/local/etherlab/ sudo nano etc/sysconfig/ethercat
In the file, enter the Ethernet devices Mac address in the MASTER0_DEVICE variable and the driver in DEVICE_MODULES variable as shown in the figure below. The values can be obtained using from the network manager (see figure above). Save and close the file.
Now, the files can be copied to the folders and proper permissions set.
cd /usr/local/etherlab/ sudo cp etc/sysconfig/ethercat /etc/sysconfig/ sudo ln -s /usr/local/etherlab/etc/init.d/ethercat /etc/init.d/
The EtherCAT master service can now be started, restarted and stopped using:
sudo /etc/init.d/ethercat start sudo /etc/init.d/ethercat restart sudo /etc/init.d/ethercat stop
To run the service without root, a rule file has to be created*:
*The for the <No> label, fill in a double digit number that is available. Type “ls /etc/udev/rules.d/” to see the occupied ones. Here, 98 was used.
cd /etc/udev/rules.d/ kwrite <No>-EtherCAT.rules
In the file add the line: “KERNEL==“EtherCAT[0-9]* “ , MODE=”0664” , GROUP=”users”.
Alternatively, to run the service without root, type the following line in the command prompt:
echo 'KERNEL=="EtherCAT[0-9]*" , MODE="0664" , GROUP = "users"' | sudo tee /etc/udev/rules.d/98-EtherCAT.rules
Installing pdServ 1.1.0
First, download and unpack:
cd /usr/local/etherlab/src/ wget http://www.etherlab.org/download/pdserv/pdserv-1.1.0.tar.bz2 tar xjf pdserv-1.1.0.tar.bz2
Continue with the installation:
mkdir pdserv-1.1.0-build cd pdserv-1.1.0-build/ cmake -DCMAKE_INSTALL_PREFIX=/usr/local/etherlab ../pdserv-1.1.0 make sudo make install
Installing Data Logging Service
Download and unpack the DLS files
cd /usr/local/etherlab/src wget http://www.etherlab.org/download/dls/dls-1.3.1.tar.bz2 tar xjf dls-1.3.1.tar.bz2
Build and install the Data Logging Service
cd dls-1.3.1/ ./configure --prefix=/usr/local/etherlab make sudo make install
In the make command, you might get the following error:
undefined reference to `fl_cursor(Fl_Cursor)`
If this occurs, type update the fltk library
sudo zypper update libfltk1
Setup the services, edit the sysconfig file to point to directories for logging.
cd /usr/local/etherlab/ kwrite ./etc/sysconfig/dls
For the achilles setup, the /usr/local/etherlab/etc/sysconfig/dls file has these contents:
#----------------------------------------------------------------------------- # # DLS sysconfig file # # $Id$ # # This file is part of the Data Logging Service (DLS). # # DLS is free software: you can redistribute it and/or modify it under the # terms of the GNU General Public License as published by the Free Software # Foundation, either version 3 of the License, or (at your option) any later # version. # # DLS is distributed in the hope that it will be useful, but WITHOUT ANY # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS # FOR A PARTICULAR PURPOSE. See the GNU General Public License for more # details. # # You should have received a copy of the GNU General Public License along # with DLS. If not, see <http://www.gnu.org/licenses/>. # #----------------------------------------------------------------------------- # # DLS data directory # DLS_DIR=/home/achilles/Data # # DLS export directory # DLS_EXPORT=/home/achilles/Data/export # # DLS export format string # This format string is passed to the strftime function (see man strftime) # and therefore supports all of its format specifiers. # DLS_EXPORT_FMT=export-%Y-%m-%d-%H-%M-%S # # DLS user. # The dlsd will switch to this user, so does the dls_ctl command. # DLS_USER=achilles # # Additional options for dlsd. # See "dlsd -h". # #DLSD_OPTIONS= #-----------------------------------------------------------------------------
Link the setup file to the OS's settings directory, and insert the Data Logging Service.
cp ./etc/sysconfig/dls /etc/sysconfig/ sudo ln -s /usr/local/etherlab/etc/profile.d/dls.sh /etc/profile.d/ sudo ln -s /usr/local/etherlab/etc/init.d/dls /etc/init.d/ sudo /usr/sbin/insserv dls <!--double check-->
To check whether the dls server is running, type ps aux | grep dls:
achilles@linux-o71q:/> ps aux | grep dls achilles 547 0.0 0.0 22376 1660 ? Ss 16:41 0:00 /usr/local/etherlab/bin/dlsd -d /home/achilles/Data -u achilles achilles 1485 0.0 0.0 10516 924 pts/1 S+ 16:46 0:00 grep --color=auto dls achilles@linux-o71q:/\>
The first line shows that /usr/bin/etherlab/bin/dlsd, the dls service, is running.
Creating, Building and Running a Real-time Model
Setting up Simulink Models
At Code Generation → Interface, choose options "Classic call interface". Also make sure that "Support for non-finite numbers is unchecked. For higher Matlab versions (>=2017?) the "classic call interface" setting is hidden in the "Commonly used parameters". Instead, look for it in the "all parameters" tab.
Setting up SSH
In order to run applications on the realtime PC when no screen is attached, you'll need to login using SSH. By default, this is not enabled after installing the way described above. If you want to use SSH use the instructions below. The source of these instructions is http://wiki.aoxoa.com/Enabling_SSH_on_OpenSuSE_13.1 .
Is the SSHD Daemon Running?
To see if the SSH Daemon is listening on port 22:
netstat -an | grep :22
If the daemon is running, you will get something like:
tcp 0 0 0.0.0.0:22 0.0.0.0:* LISTEN tcp 0 0 :::22 :::* LISTEN
If the daemon is not running, you will get nothing.
Enabling the SSHD Daemon
su - systemctl enable sshd.service
To Start the Service
systemctl start sshd.service
