EtherLab^® EtherCAT Master

SimWB can act as an EtherCAT master using the low level driver and API provided by EtherLab^®. That is, SimWB can be configured to act as a master to query EtherCAT remote I/O slave devices on the network.

The EtherCAT master runs on a standard Ethernet interface whose driver is provided by the Linux kernel.
Before running an EtherCAT master under SimWB, you must first install the package provided by EtherLab^®.

Reference Information

I/O Card Model Number

N/A. Use system ethernet device.

I/O Driver Model Number

N/A.

I/O Module License:

ICS-SWB-1250 : EtherCAT master license for 10 slaves.

ICS-SWB-1251 : EtherCAT master license for 10 additional slaves.

EtherLab^® Package Installation

To install the EtherLab^® package, use the following steps:

• On the real-time host, open a terminal and execute cd /usr/local/ccursim/etherlab.
• The install_ecatmaster.sh script downloads the latest source code for the master, compiles and installs it. The script also dynamically builds a utility required by SimWB.
  Run the script by executing ./install_ecatmaster.sh.
  If you want to install the master manually, see the legacy instructions. However, you must consult the install_ecatmaster.sh script and build the slavesdos utility.
• Assuming EtherLab^® is installed properly, to see the list of the EtherCAT slaves connected to your network, use:
  /opt/etherlab/bin/ethercat slaves
  The output of the command is similar to:

         0  3:0  PREOP  +  EK1100 EtherCAT-Koppler (2A E-Bus)
         1  3:1  PREOP  +  EL4001 1K. Ana. Ausgang 0-10V, 12bit
         2  3:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0.5A
         3  3:3  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0.5A
         4  3:4  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
         5  3:5  PREOP  +  EL4104 4Ch. Ana. Ausgang 0-10V, 16bit
         6  3:6  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V, 16bit
         7  4:0  PREOP  +  EK1100 EtherCAT-Koppler (2A E-Bus)
         8  4:1  PREOP  +  EL3001 1K.Ana. Eingang  +/-10V
         9  4:2  PREOP  +  EL1004 4K. Dig. Eingang 24V, 3ms
         10  4:3  PREOP  +  EL1014 4K. Dig. Eingang 24V, 10µs
         11  4:4  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10µs
         12  4:5  PREOP  +  EL1859 8K. Dig. Eingang 24V, 3ms, 8K. Dig. Ausgang 24V, 0.5A
         13  4:6  PREOP  +  EL1819 16K. Dig. Eingang 24V, 10µs
         14  4:7  PREOP  +  EL3164 4K. Ana. Eingang 0-10V
         15  4:8  PREOP  +  EL3162 2K. Ana. Eingang 0-10V
      

Tune System for Optimal Real-Time Performance

To optimize the EtherCAT bus performance, you can perform the following tuning. Append the /etc/rc.d/rc.local file with the commands that follow to invoke these optimizations every time the system reboots.
Note: The following instructions assume that eth1 is configured as the EtherCAT master.

• Set RX/TX ring parameters to 0

  
  ethtool -G eth1 rx 0 tx 0

• Set coalesce options

  
  ethtool --coalesce eth1 adaptive-rx off adaptive-tx off rx-usecs 0 rx-frames 0 rx-usecs-irq 0 rx-frames-irq 0

• Direct eth1-related IRQs to a shielded CPU. For example, CPU 2. To obtain a list of the relevant IRQs, type cat /proc/interrupts | grep eth1.

  echo 4 >/proc/irq/125/smp_affinity
  echo 4 >/proc/irq/126/smp_affinity
  echo 4 >/proc/irq/127/smp_affinity
  echo 4 >/proc/irq/128/smp_affinity
  echo 4 >/proc/irq/129/smp_affinity
  echo 4 >/proc/irq/130/smp_affinity
  echo 4 >/proc/irq/131/smp_affinity
  echo 4 >/proc/irq/132/smp_affinity
  echo 4 >/proc/irq/133/smp_affinity
  

Use Dedicated Port for Optimal Real-Time Performance

It is recommended that you dedicate an ethernet port for the EtherCAT bus to ensure real-time performance. Also, configure the Network Manager to not reset/auto-connect to this port.

SimWB I/O Mapping

Mapping the PDO (process data object) of EtherCAT slaves to RTDB items is a 3-step process.

• Pick the slave PDO you want to map.
• Drag and drop the PDO(s) onto one of the domains (input or output) in the domain list below.
• Select a specific PDO and click on the checkbox next to the variable you want to map in the list to right in the mapping panel.

Slave PDO list:   When you open the mapping panel for the EtherCAT master, the list of online slaves is displayed automatically. You will not be able to configure the slave and map PDOs to RTDB items if your EtherCAT network is off or you have no slaves connected to it. All the slave PDOs available for reading or writing are visible in the list.   You can drag and drop TxPDO(s) (Tx from the viewpoint of the slave) into the input domain (input into SimWB, DomainIn). Similarly, you can drag and drop RxPDO(s) into the output domain (DomainOut).
Mailbox COE (CANOpen over EtherCAT):   This tab displays the slave SDOs (Service Data Objects) and allows you to configure their values. Refer to your slave documentation for the function of particular SDOs.   The list is read from the online slaves and saved in the SimWB RTDB so that it does not have to be re-read every time the panel is open as this is a slow process. The list can be refreshed by clicking on the Read from Slaves button. You might have to set slave SDOs to specific values to open slave PDOs that are not available in the default on state configuration for the slave. Click on the SDO value field to edit the value. Only writable entries can be edited this way. If you changed an SDO value, you can update the slave immediately by clicking on the Download SDOs button. You should then go back to the slave PDO list and refresh the list of PDOs by clicking on the Rescan Slaves button in the Online Slaves tab.   To write specific values to the SDOs on test startup, before the EtherCAT master I/O task starts scanning the network, you must check the corresponding checkbox in the Set on Start column. The software writes the values for the SDOs with Set on Start selected before configuring the slave PDOs.
Mapping into Input & Output Domains:   Drag a collection of PDOs from the Online Slaves list and drop them into the corresponding domain. You can now select a specific PDO and map it by selecting and checking the appropriate box in the RTDB item list in the right-hand side. Only RTDB items corresponding to the PDO data type (Analog / Digital - Single bit) will be displayed in the RTDB item list.

Troubleshooting

If you encounter unexpected behavior, the output of the following commands may help in debugging the issue:

• /opt/etherlab/bin/ethercat slaves
• /opt/etherlab/bin/ethercat pdos
• dmesg (Look at any entries that are related to EtherCAT.)

EtherLab^® Package Installation (Legacy Method)

• Visit the EtherLab Master website to download the package.

• Before you can build the EtherLab^® EtherCAT modules, you must prepare the RedHawk kernel for module building with:
  cd /lib/modules/`uname -r`/build (Notice the back ticks)
  

• Once inside the kernel source folder, run:
  ./ccur-config -c -n (This must be run as root)

• Download ethercat-1.5.2.tar.bz2 from the Download page into a folder of your choice.

• cd into the download folder and extract the archive with:

  tar xvjf ethercat-1.5.2.tar.bz2
  cd ethercat-1.5.2
  ./configure --disable-8139too --disable-e100 --disable-e1000 --disable-e1000e --disable-r8169 --enable-hrtimer --disable-eoe --enable-sii-assign -with-devices=4
  (Type configure --help for all the available configure options.)
  Do not change the default installation location, because SimWB relies on the default installation to find the ethercat executable.
  The options specified above ensure that the native EtherLab^® ethernet drivers are not built by default. If you do not have the right combination of kernel version and driver, configure will most likely fail when you try to build the native drivers.
  The EtherLab^® software always provides the 'generic' driver which uses the ethernet device via the driver provided by the kernel. So the configure invocation above will make the 'generic' driver available.

• After configure has completed successfully, build the package with:
  make
  make modules
   
  and install it : (you must be root to install)
   
  make modules_install install
  depmod -ae
   
  The package will be installed in /opt/etherlab.
   

• Before you can start EtherCAT, you must specify the ethernet device and driver that EtherCAT will use.
  
  • Copy the the configuration file to /etc/sysconfig:
    cp /opt/etherlab/etc/sysconfig/ethercat /etc/sysconfig
    
  • Edit the /etc/sysconfig/ethercat file and enter a value for the MASTER0_DEVICE variable. For instance:
    MASTER0_DEVICE="90:E2:BA:38:4D:1C"
    Here, 90:E2:BA:38:4D:1C is the MAC address of the ethernet device you will use as the EtherCAT master. To get the MAC addresses of the ethernet devices available on your system, use ifconfig|grep HWaddr.
    Use a dedicated ethernet device for the master, one that is not used in your current network configuration.
    In the same file(/etc/sysconfig/ethercat), set the ethernet device driver with:
    DEVICE_MODULES="generic"
     
    
• Copy the startup file to /etc/init.d/:
  cp /opt/etherlab/etc/init.d/ethercat /etc/init.d/
• Now, you can start EtherCAT with:
  /etc/init.d/ethercat start
   
  To see any errors that are generated, use dmesg.
  You should now have the ec_generic and ec_master modules loaded in the kernel. Use the command lsmod to view the list of modules loaded in the kernel.
  If any EtherCAT slaves are connected to the ethernet device, the dmesg command will report the connection using a line similar to:
   
  EtherCAT 0: 16 slave(s) responding on main device.
   
• EtherLab^® comes with a general purpose utility called ethercat, which you can use to list all the EtherCAT slaves connected to your network. This utility is installed in /opt/etherlab/bin/. For more information about the EtherLab^®, see the INSTALL file in the package directory.
  Assuming EtherLab^® is installed properly, to see the list of the EtherCAT slaves connected to your network, use:
    /opt/etherlab/bin/ethercat slaves

  The output of the command is similar to:

         0  3:0  PREOP  +  EK1100 EtherCAT-Koppler (2A E-Bus)
         1  3:1  PREOP  +  EL4001 1K. Ana. Ausgang 0-10V, 12bit
         2  3:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0.5A
         3  3:3  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0.5A
         4  3:4  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
         5  3:5  PREOP  +  EL4104 4Ch. Ana. Ausgang 0-10V, 16bit
         6  3:6  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V, 16bit
         7  4:0  PREOP  +  EK1100 EtherCAT-Koppler (2A E-Bus)
         8  4:1  PREOP  +  EL3001 1K.Ana. Eingang  +/-10V
         9  4:2  PREOP  +  EL1004 4K. Dig. Eingang 24V, 3ms
         10  4:3  PREOP  +  EL1014 4K. Dig. Eingang 24V, 10µs
         11  4:4  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10µs
         12  4:5  PREOP  +  EL1859 8K. Dig. Eingang 24V, 3ms, 8K. Dig. Ausgang 24V, 0.5A
         13  4:6  PREOP  +  EL1819 16K. Dig. Eingang 24V, 10µs
         14  4:7  PREOP  +  EL3164 4K. Ana. Eingang 0-10V
         15  4:8  PREOP  +  EL3162 2K. Ana. Eingang 0-10V
  

• To start the EtherCAT service every time the system reboots, use:
  chkconfig ethercat on

Note:  The libraries corresponding to the EtherLab® package are by default installed in the /opt/etherlab/lib directory, which is not in the default system path of dynamic libraries. You should make a link to the library with in the /usr/local/lib/ directory. cd /usr/local/lib/ ln -sf /opt/etherlab/lib/libethercat.so.1.0.0 ln -sf /opt/etherlab/lib/libethercat.so.1 ln -sf /opt/etherlab/lib/libethercat.so          To update the dynamic linker run-time bindings, execute ldconfig. If the run-time linker is not updated, then you could run into the following error when you start the test: elabecatm_in: error while loading shared libraries: libethercat.so.1: cannot open shared object file: No such file or directory