How-to Setup EtherCAT for LinuxRT

<This page is currently under active development/revision.  Please contact  Jesus Vasquez <jvasquez@slac.stanford.edu> for more information or questions.>

This page covers how to setup a new EtherCAT device and integrate into the EPICS Control System.  The following topics are included:

• EtherCAT Resources & Reference Material
• linuxRT PC Set-up
• Configuring the $IOC/sioc-<area>-<subsystem##> Directory where ## is a 2-digit number 01-99.
  
• EtherCAT linuxRT Configuration
• EtherCAT Template for Creating Epics Application
• Configuring EtherCAT Epics Application
• Debugging Tips

EtherCAT Resources & Reference Material

The following resources and reference material provide an introduction to the EtherCAT technology:

• EtherCAT Overview
• EtherLAB Master & Kernel Modules
• Bus Scanner & EPICS Asyn Driver
  
  

linuxRT PC Set-up

In the SLAC environment, we are currently running EtherCAT on industrial PC's running linux with a pre-emptive real-time patch (linuxRT).  Before configuring for EtherCAT, the very first step is to set-up a new linuxRT host.

• For new users, please reference the following page: Diskless Boot of LinuxRT or Centos7 - Quick Start-up Highly recommend viewing this diagram: LinuxRT_Diagram
  

   

  Table 1

  Facility	LinuxRT Account	LinuxRT  Group	Comment
  Development	laci	lcls
  LCLS	laci	lcls
  LCLS-II			not yet available
  FACET	flaci	facet	linuxRT is built with laci as the default account, users must add  facet group, user and  password
  Test-Facility	acctf	?	linuxRT is built with laci as the default account, users must add  test-facility group, user and password

Verification checks on linuxRT machines:

• Please see $IOC/cpu-<bld>-<name>/README on instructions on how to power cycle machines remotely through the use of ipmi commands
• Once you set-up your linuxRT machine and boot up on development for instance, log into laci on your linuxRT system (ref: Table 1). ( ssh laci@cpu-<bld>-<name>)
• Test if your machine is running real-time linux using  uname -a

EtherCAT linuxRT Configuration

We are currently using Etherlab's EtherCAT Master module, which can be found under the package area.  The kernel-modules.cmd file needs to be updated to include the following:

1. Location of EtherCAT kernel drivers
2. Install kernel drivers
3. Network configuration
4. EtherCAT system configuration & set-up
5. Start scanner process

Update the following lines of code in your $IOC/cpu-<>-<>/kernel-modules.cmd.  The following code excerpts are from $IOC/cpu-b084-hp03/kernel-modules.cmd

This current code stanza  defines the location for the EtherCAT kernel drivers.

The following stanza provides the network configuration, installs kernel drivers, and performs some EtherCAT system configuration & set-up

Next, need to add the following lines to start the scanner process up automatically.

Verification checks on linuxRT machines:

•  Test if your machine has the Etherlab EtherCAT driver module loaded.

• If the slaves are connected with the setup, the ethercat command line tool can help visualize it.

• Another helpful ethercat command line took is ethercat master

Configuring the $IOC/sioc-<>-<> Directory

The $IOC/vioc-<>-<> directory created for this EtherCAT application needs the follow items:

• scannerStartup.sh (where should we put a "master" scannerStartup.sh for people to copy/point to)
•  Proposal: put generic scannerStartup.sh under $IOC/common/ethercat.  Script has been modified to pass in the vioc name from when the script is called from the kernel-modules.cmd
  
  • so vioc specific information (for vioc-ltu0-mc01) was moved to the kernel-modules.cmd  => have to think about use case where multiple subsystems share cpu  (see above solution)
    
  • OR do we keep it in kernel-modules.cmd (this should be apart of the linuxRT discussion)
    
• Create a bin directory  (currently under discussion to rename this "bin" directory to avoid confusion)
• Proposal: rename "bin" to "scanner" and use symbolic links to point to scanner binary and scanner.xml in epics application
  
• In the bin directory, create a symbolic link "scanner" that points to your scanner binary in your epics application (<top>/bin/linuxRT_glibc-x68_64/scanner)
  • OH! scanner binary is NOT specific to your application.  Should point to the package area.
    
• In the bin directory, create a symbolic link "scanner.xml" that points to your scanner.xml in your epics application (<top>/etc/scanner.xml)
  

Example from vioc-b084-tm01:

EtherCAT Template for Creating Epics Application

When starting a new EtherCAT application, it is highly recommended to start a new epics application and vioc using the slac_ethercat template. 

The following command creates a new epics command using the slac_ethercat template.

Generate a vioc for your application.  We are using the following format for linuxRT IOC's:  vioc-<area>-<subsystem>

Choose your target architecture:

Choose the application that you want your new vioc to boot:

You have now created a baseline EtherCAT application.

(For more reference material on getting started with EPICS: CH. 2 Getting Started)

Configuring EtherCAT Epics Application

The EtherCAT application has two parts.

1. The scanner process which scans the bus
2. The EPICS IOC application
   
   

Before being able to successfully run the application, some clean-up and configuration are necessary in the following areas:

1. <top>/etc/
2. <top>/configure/RELEASE
3. <top>/<app_name>/Db/Makefile
4. <top>/iocBoot/vioc-<>-<>/st.cmd
   
   

The first step specific to an EtherCAT application, is creating a chain.xml file for the scanner process.  The scanner process will open up a unix socket for communication with the IOC.  If using the slac_ethercat template, you should already have a directory named /etc under <top>.  Otherwise, you will been to create a directory called /etc.  This directory will consist of a Makefile, chain.xml, and a scanner.xml.  The scanner.xml will be automatically generated upon building the application. 

The Makefile should consist of the following lines:

However, the chain.xml needs to be manually created based off the devices in your EtherCAT chain.

This is an example of a chain with just one motion control device (ref: $APP/users/namrata/EtherCATest/etc):

Here is another example with two slave devices for an EtherCAT coupler and an analog output device for reading temperature from RTD's (ref: $APP/users/ababbitt/LCLS-II/TEMPERATURE/etc):

The device name needs to match the name given by the xml device templates found here: $PACKAGE_TOP/ethercat/<ethercat_version_number>/etc/xml (need to confirm....).

To obtain the revision number for the device you will need to use the slaves ethercat command line tool on your linuxRT machine (aka the EtherCAT Master).

Upon making your application, the scanner.xml file will be automatically generated in the /<top>/etc directory.  A scanner binary will be generated under /<top>/bin.  You will need to create symbolic links to both of these items under $IOC/vioc-<>-<>/bin directory as previously mentioned.

NOTE: If you are using a brand new module, it may not currently exist in the EtherCAT module.  You can check whether you device is supported by looking in the epics modules ethercat area under the /etc/xml directory.

Epics ethercat module: ECASYN=$(EPICS_MODULES)/ethercat/$(ECASYN_MODULE_VERSION)/etc/xml - contains the xml files from the vendor for the device families currently supported.

Any new devices should be integrated into the EtherCAT module.  Please contact the EtherCAT module owner:

• Jesus Vasquez: jvasquez@slac.stanford.edu
  

Now that the chain.xml file has been created to generate the scanner.xml file, the second part is to configure and clean-up your epics application to only include the elements that you need.

• Under <top>/configure/RELEASE, remove any modules you are not using for your application (the slac_ethercat is a motion control based example)

• Under <top>/<app_name>/Db/Makefile, only include the templates to be installed that you are using (each slave device should have an associated template)
  Here is an example of using the slac_template for a non-motor application:

  ## Install Protocol File:  #DB_INSTALLS += $(CAENN1470)/db/caenN1470.proto  ## ==================================================== DB_INSTALLS += $(ECASYN)/db/EK1101.template DB_INSTALL S+= $(ECASYN)/db/EL3202-0010.template #DB_INSTALLS +=$(MOTOR)/db/basic_asyn_motor.db   DB_INSTALLS += $(ASYN)/db/asynRecord.db

  NOTE: Should be using DB_INSTALLS to be using the common templates found in the epics modules (want to avoid unnecessary copy and paste of template files or database records)
  
  

• <top>/iocBoot/vioc-<>-<>/st.cmd
  Update the st.cmd to only load the database records specific to your application. The st.cmd for all EtherCAT applications must include the following items.  (Please reference the st.cmd file after using the slac_ethercat template for additional motion control related steps.)

Load the records for the EtherCAT components and pass in the appropriate macros as defined in the template files. 

NOTE: The "PORT" name is the name defined in the chain.xml file (also is located at the end of the scanner.xml file).

Verification checks on development machine (preferably lcls-dev3):

Check that your python version is correct (the scripts used to generate the chain.xml are python-based):

• • Python version: Python 2.7.9
  • export the correct version to the path

Debugging Tips

• Check that the ethercat kernel module is installed: ls /dev/EtherCAT0

• Manually start scanner process on EtherCAT Master (linuxRT machine)

  On a linuxRT machine: <path_to_scanner_binary> -f <rate_in_hz> <path_to_scanner_xml> <path_to_unix_socket_created_by_scanner> <max_message_size>    Example (from directory containing scanner binary): ./scanner -f 100 ../../etc/scanner.xml /tmp/sock1 100