Page History

...

• For new users, please reference the following page: LinuxRT Quick Start-up For New Users
• Highly recommend viewing this diagram: LinuxRT_Diagram
  
  

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, log in as laci to your linuxRT system. ( ssh laci@cpu-<bld>-<name>)
• Test if your machine is running real-time linux using  uname -a

...

Verification checks on linuxRT machines:

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

...

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

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.

...

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

...

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:

TOP=..                                                                   

include $(TOP)/configure/CONFIG

install:

    /usr/bin/python $(ECASYN)/etc/scripts/expandChain.py  chain.xml > scanner.xml

clean:

    rm -f scanner.xml

    rm -f EK1101-EtherCAT.template

distclean: clean

realclean: clean

...

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)
• Create a bin directory
• 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)
  
• 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.

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 owners:

• Who wants to be the EtherCAT module owner?

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_INSTALL += $(ECASYN)/db/EK1101.template DB_INSTALL += $(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

  
   

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):

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 above.

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 following areas in the EtherCAT module area.

XML

Templates

For the long-term, any new devices should be integrated into the EtherCAT module.  Please contact the EtherCAT module owners:

• Who wants to be the EtherCAT module owner?

1. Add the scanner.xml file in a bin folder along with the scanner binary in $IOC/vioc-b34-mc23 folder.

2. Add the script to start the scanner as a linux screen process. (ref: $IOC/cpu-b34-mc23)

3. Start the scanner at 100Hz frequency.

...

• Check that your python version is correct:

Python version: Python 2.7.9

export the correct version to the path

...