2.1. PRU ICSS EtherCAT Slave User Guide

2.1.1. Introduction

PRU-ICSS EtherCAT package is designed for the Sitara processor family (with PRU-ICSS IP) to enable customers add EtherCAT Slave protocol support to their system.

2.1.2. System Requirements

2.1.2.1. Supported Devices

  • AM64x EVM

2.1.2.2. Component Version

Component Version
Processor SDK for AM64X 1.0.0

2.1.4. Directory Structure

|   |--- docs

|       |---EtherCAT_Slave_Datasheet.pdf

|       |---PRU-ICSS-EtherCAT_Slave_01.00.09_manifest.html

|   |--- examples

|       |--- board

|           | --- common

|           | --- evmAM64x

|           | --- include

|       | --- osal

|       |--- ethercat_slave

|           | --- esi

|       |--- tools

|           | --- bin2header

|   |--- protocols

|       |--- common

|           |--- include

|           |--- source

|       |--- ethercat_slave

|           |--- docs

|               |--- doxygen

|           |--- ecat_appl

|               |--- baremetal

|               |--- EcatStack

|               |--- esi

|               |--- evmAM64x

|           |--- firmware

|               |--- g_v1.0

|           |--- include

|           |--- lib

|               |--- am64x

|                   |--- r5f

|           |--- projects

|               |--- ccsproject_args

|                   |--- AM64x

|   |--- third_party

|       |--- protocols

|               |--- ethercat_slave

|                   |--- include

|                   |--- patch

|                   |--- stack_lib

Note

Refer to install path to get updated view of the changes in directory structure

2.1.5. Example Project Overview

TI has created two how-to videos that cover the information in this user guide. These videos break down all of the necessary steps to get your application up and running. Watching the videos while following along with the user guide is the easiest way to get started.

Note

Because there are many steps involved, you are encouraged to read through each of these sections to get the full picture before trying to create and run the example applications.

Building and running the EtherCAT slave example applications is broken down in to the following sections in the user guide:

  • Generating Project files
    • This section covers how to use the projectCreate_core_sdk.bat/.sh scripts to generate the CCS example projects after you have downloaded and installed PRU-ICSS-ETHERCAT-SLAVE and Processor SDK RTOS for your platform (see Component Version).
  • Running EtherCAT Slave Application
    • This section covers the differences between the Simple Demo Application and the Full Feature Demo Application and loading the application via SD card, QSPI, or CCS.
  • Building full feature EtherCAT Slave Application
    • This section covers the additional steps needed to build the Full Feature EtherCAT Slave Application. Specifically, this section covers downloading the EtherCAT stack source code and patching it for the example application.

At a high level, you will be completing the following steps as you make your way through the guide or our how-to videos:

  • Setting up your hardware
  • Installing necessary software
    • CCS
    • Processor SDK RTOS
    • PRU-ICSS-ETHERCAT-SLAVE
    • EtherCAT slave stack code (necessary for Full Feature Application)
    • TwinCAT EtherCAT master
  • Generating and building the example application
  • Loading and running the application
  • Validating application results using TwinCAT

2.1.6. Generating Project files

2.1.6.1. Steps to generate Project files

  • Setup the environment variables

    • Edit the file [INSTALL-DIR]/protocols/ethercat_slave/projects/projectCreate_core_sdk.bat or .sh to align to the environment in your machine. All these paths should be accurate and mandatory; otherwise it will cause errors.

      • CCS_INSTALL_DIR - Set the path where the recommended version of CCS is installed in user machine. For example, if CCSv10.1.1 is installed in default path, set it to “C:\ti\ccs1011\ccs”.

      Note

      Use the path up to where the folder ‘eclipse’ is located.

      • CCS_WORKSPACE_LOC - Set the CCS workspace location. This folder will be created if it doesn’t exist already.
      • IA_SDK_HOME - Specify the IA_SDK_HOME based on the the directory where the industrial package is installed. If the package is installed in a custom directory, make sure this path is modified properly.
      • PDK_INSTALL_PATH - Set the path where PDK RTOS package is installed (Refer to default path in projectCreate_core_sdk.bat)

      Note

      Use the path up to where the folder ‘ti’ is located.

      • PROJECT_CREATE_DIR - Set the folder where the created project will be kept. User can import the projects from this directory to CCS
      • PROJECT_CREATE_OPTIONS_FILE_DIR - Specify the directory where the project create options files are kept. This folder contains the *.txt files which specify the project settings (linked files, predefined symbols, compiler and linker options for a specific project)

  • Open Command/Shell Prompt and navigate to [INSTALL-DIR]/protocols/ethercat_slave/projects

  • Run projectCreate_core_sdk.bat or projectCreate_core_sdk.sh. The batch file takes three mandatory command line arguments (The mandatory arguments are case sensitive!)

Usage format: projectCreate_core_sdk.bat [SOC] [PROCESSOR] [PROJECT_NAME]

  • [SOC]

    • The valid values for first command line argument [SOC] are
      • AM64x - To generate a project specific to AM64x

  • [PROCESSOR]

    • The valid values for second command line argument [PROCESSOR] are
      • r5f - To generate a project specific to R5F core

  • [PROJECT_NAME]

    • The valid values for third command line argument [PROJECT_NAME] to be used with EtherCAT slave installer package

      • ethercat_slave_full - to generate EtherCAT slave full application project
      • ethercat_slave_demo - to generate EtherCAT slave demo application project
      • ethercat_slave_full_library_mode - to generate project for EtherCAT slave full application in FWHAL library mode
      • ethercat_slave_demo_library_mode - to generate project for EtherCAT slave demo application in FWHAL library mode
      • ethercat_slave_fwhal_lib - to generate project for EtherCAT slave FWHAL library

      Note

      For more details on FWHAL mode projects, please see FWHAL Library Mode Application section.

Note

Ensure that the workspace provided in CCS_WORKSPACE_LOC variable is not open in Code Composer Studio when executing projectCreate_core_sdk.bat or projectCreate_core_sdk.sh. If it is open, the eclipsec may throw errors

  • Usage example 1 : projectCreate_core_sdk.bat AM64x r5f ethercat_slave_demo
    • To generate the project files for EtherCAT slave demo application for AM64x R5F core
  • Usage example 2 : projectCreate_core_sdk.bat AM64x r5f ethercat_slave_full
    • To generate the project files for EtherCAT slave full application for AM64x R5F core
  • Usage example 3 : projectCreate_core_sdk.bat AM64x r5f ethercat_slave_full_library_mode
    • To generate the project files for EtherCAT slave full application in FWHAL library mode for AM64x R5F core

Note

If the project create is successful, the generated project files will be found in [INSTALL-DIR]/protocols/ethercat_slave/projects/[PROJECT_NAME]_[SOC]_[PROCESSOR]

Note

Default PRU-ICSSG instance used for EtherCAT is PRU-ICSSG1. For changing the PRU-ICSSG instance to be used, the PRUICSS_INSTANCE macro needs to be set accordingly in the [INSTALL-DIR]/protocols/ethercat_slave/include/tiesc_soc.h file.

2.1.6.1.1. FWHAL Library Mode Application

ethercat_slave_full and ethercat_slave_demo projects include files for application, driver and firmware in the project. In order to remove inclusion of driver and firmware from the project, there is a separate application mode which includes only application files and links a FWHAL library consisting of firmware and driver sources. This FWHAL library is present in [INSTALL-DIR]/protocols/ethercat_slave/lib/[SOC]/[PROCESSOR] folder. For creating applications with this mode, ethercat_slave_full_library_mode or ethercat_slave_demo_library_mode should be used for [PROJECT_NAME] while running projectCreate_core_sdk script. If you want to rebuild the FWHAL library, you can create the project using ethercat_slave_fwhal_lib for [PROJECT_NAME]. Building it will automatically update the library in [INSTALL-DIR]/protocols/ethercat_slave/lib/[SOC]/[PROCESSOR] folder.

2.1.6.2. More info

The projectCreate_core_sdk.bat or.sh utilizes the project arguments provided in [INSTALL-DIR]/protocols/ethercat_slave/projects/ccsproject_args to generate the project file

2.1.7. Running EtherCAT Slave Application

Note

NOTE 1: Package supports two different versions of EtherCAT application.

1. Simple Demo Application  - An EtherCAT sample application built
using  pre-built EtherCAT stack library. This allows limited development using SSC5.12 stack library via Sample Application Interface which provides controlling 32- bit input and 32-bit output. Object dictionary adaptation is not possible in this evaluation version. This will be the default configuration for EtherCAT. The project files for this application can be generated following Generating Project Files.. The example application will be delivered in source, but the EtherCAT stack will be delivered in object format only.
2. Full Feature Demo Application  -  This is a full-fledged
application and provides full flexibility and configurability. However this application need access to complete stack source. As per the SLA terms, TI cannot distribute the stack (Beckhoff Slave Sample Code) in source format. Therefore, to build this application, user must get the SSC 5.12 source code from ETG website and apply the provided patch. The project files for this application can be generated following Generating Project Files. For more information, refer the section on “Building Full Feature EtherCAT Application” of this document.

NOTE 2:  Both EtherCAT applications support non-volatile storage of ESI EEPROM. The application writes the data into non-volatile QSPI memory only in INIT and PREOP states. This can be disabled or enabled on full featured application by defining/undefining EEPROM_SPI macro in tiescbsp.h. This feature cannot be modified in limited demo

To test the TI EtherCAT Slave sample application, the user first needs to create the project files.

  1. For Simple Demo Application use ethercat_slave_demo as the command line argument
  2. For Full Feature Demo Application use ethercat_slave_full as the command line argument

The created project can be imported to the recommended version of CCS and built. Upon successful build, ethercat_slave_demo_[SoC]_arm.out or ethercat_slave_full_[SoC]_arm.out will be generated. The SD card image named app will also be generated by the default post-build scripts of the CCS project. This can be flashed to QSPI or copied to SD card. Please see the Getting Started Guide for details on building an application. Alternatively, ethercat_slave_demo_[SoC]_arm.out or ethercat_slave_full_[SoC]_arm.out can be load/run from CCS to Cortex-A CPU of Sitara processor. The application uses the LED light controls to demonstrate the EtherCAT Slave interface.

To test TI EtherCAT slave sample app - one can use TwinCAT or any other compatible EtherCAT master. Below are the steps to use TI slave with TwinCAT.

2.1.7.1. TI_ESC slave setup with TwinCAT3

  1. Install TwinCAT3. A 7 days free trial license (can be renewed indefinitely for evaluation purpose) is available for free download from the Beckoff website TwinCAT 3 Download. Select the eXtended Automation Engineering (XAE) mode of installation.

  2. Copy the ESI file to <Drive>:\TwinCAT\3.1\Config\Io\EtherCAT folder

    1. ESI file for EtherCAT Slave demo application is [INSTALL-DIR]/examples/ethercat_slave/esi/TiEtherCATLib.xml
    2. ESI file for EtherCAT Slave full application is [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/esi/TI_ESC.xml
    3. ESI file for EtherCAT TI ESC SPI Mode (ASIC Mode) Slave application is TMDSECATCNCD379D EtherCAT slave (SPI).xml available in ControlSUITE

  3. Start the TwinCAT XAE Shell

  4. Create a new TwinCAT XAE Project (XML format): File > New > Project > TwinCAT Project

    ../../../_images/EtherCAT_Slave_TwinCAT_Project_Create1.PNG

  5. Go to TwinCAT > Show Real Time Ethernet Compatible Devices and Install TwinCAT RT Ethernet intermediate driver. For best performance, it is recommended to use a compatible NIC card listed Supported Network Controller by Beckhoff Ethernet Driver . For the first time only you need to set the PC’s Ethernet port, which is used as the EtherCAT port. Go to TwinCAT > Show Realtime Ethernet Compatible Devices.

    ../../../_images/EtherCAT_Slave_TwinCAT_NIC_Detection1.PNG ../../../_images/EtherCAT_Slave_TwinCAT_NIC_Detection_21.PNG

    Note

    Please check if the ethernet adapter is listed below “Installed and ready to use devices” before attempting to run TwinCat demo. A tip, if your computer go to sleep and after awake it TwinCAT lost connection with slave(s) and/or is not able to discover EtherCAT IO devices, you can fix this issue by going in TwinCAT to your Ethernet adapters, and Disabling / Enabling your NIC.

  6. Connect Ethernet cable from TwinCAT PC to EtherCAT IN/Port0 of the default PRU-ICSS instance on IDK(See the table below to find the default instance). If you have multiple IDKs in chain, please connect from EtherCAT OUT/Port1 to IN/Port0 of next IDK. For the last IDK in chain, OUT/Port1 will be left open (if NOT using redundancy mode).

  7. Power up the device.

2.1.7.2. Starting EtherCAT application

  1. On powering up the device and loading the application, you should see digital output LED’s 2, 4, 6 and 7 on (except for AMIC11x ICE, where LEDs 2 and 5 should be on). This indicates that slave is up and in INIT state.

  2. In Solution Explorer, go to TwinCAT project > I/O > Devices. Right click on Devices and select Scan. Press OK in the next dialog to start scanning for EtherCAT devices.

    ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection1.PNG

  3. Once an EtherCAT compatible device has been detected on this Ethernet port, the following dialog shows up. Note that there is a tick mark next to the adapter to which the IDK is connected. Press OK and confirm to start “Scan for boxes”.

    ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection_21.PNG

  4. TI Box n(TIESC) will be detected automatically. The TI device will be listed “Box n (TIESC-*)”. Press Yes to activate Free Run. This will put TI ESC into OP mode. TIESC number is based on the platform and application. Please check the ESI file for more details.

    ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection_31.PNG

    Note

    If running TwinCAT 2 on Windows XP, now select Device1 (EtherCAT) and goto Actions > Select Set/Reset TwinCAT to Config Mode or use shortcut SHIFT-F4. Alternatively, if running TwinCAT 3 on Windows 7, now select Device1 (EtherCAT) and goto TwinCAT and then Reload Devices.

  5. The EtherCAT device state can be displayed by selecting a Device (Double click on Device) and then selecting the Online tab. The device should be in the OP state with no Lost Frames or Tx/Rx Errors.

    ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection_41.PNG

  6. The user can control 8 digital out LEDs using TwinCAT. Expand the box to see Process Data Inputs(PDI) and Outputs(PDO).

    • Right-click on “Box n (TIESC-*)” > RxPDO > 32Bit Output. Select Online Write.

      ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection_51.PNG

    • Enter the value in hexadecimal format, where each bit in the lowest 8 bits represents an output. Changing the output value will set/clear the appropriate LED(s).

      ../../../_images/EtherCAT_Slave_TwinCAT_Slave_Detection_61.PNG

Note

The images shown above are from EtherCAT Slave demo application. If you load EtherCAT Slave full application by following steps from Building full feature EtherCAT Slave Application, you will see LED1 to LED8 in “Box n (TIESC-*)” > DO Outputs > LED. Each LED can be turned on and off by selecting online write and setting the value to 1 and 0 respectively.

Note

For running EtherCAT slave in DC mode, please see Building full feature EtherCAT Slave Application section.

2.1.8. Building full feature EtherCAT Slave Application

The EtherCAT example application provided in [INSTALL-DIR]/examples/ethercat_slave folder is a limited development application. To have a full development capability on Sitara processor, it is necessary to get the EtherCAT Slave Stack Code (SSC) from Beckhoff and build this for Sitara processors. Ethercat full mode example application provides all board specific implementation sources for EtherCAT and a patch file to modify Beckhoff source files for Sitara processors. This application can be found in [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl. This folder also includes the configuration xml file to be used for testing and it can be found in[INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/esi folder.

The steps for building full feature EtherCAT application using Beckhoff stack source code are given below.

  1. Download EtherCAT stack version 5.12 from ETG website and extract it to a local folder.
  2. Generate the patched EtherCAT Slave stack code source files using any one of the below mentioned methods
    1. Apply the patch on the extracted Slave stack code source files
    2. Use SSC Tools to generate patched source files from the Slave stack code
  3. Copy the patched Beckhoff source files (.c and .h) to [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/EcatStack
  4. Generate CCS project following Steps to generate Project files
  5. Launch CCS and import ethercat_slave_full application project found at the Project create directory (say, [INSTALL-DIR]/protocols/ethercat_slave/projects) to CCS
  6. Define macros in ecat_appl\EcatStack\ecat_def.h as required for your application.
    1. Ensure that TIESC_HW is set to 1
    2. For running default application, set TIESC_APPLICATION to 1 and CiA402_DEVICE to 0
    3. For running CiA402 application, set TIESC_APPLICATION to 0 and CiA402_DEVICE to 1.
      1. Please note `Option #2 <PRU_ICSS_EtherCAT.html#generating-ethercat-sources-using-beckhoff-ssc-tool-option-2>`__ will NOT work for CiA402 application. Please use `Option #1 <PRU_ICSS_EtherCAT.html#generating-ethercat-sources-using-the-patch-file-option-1>`__ to generate the sources.
  7. Build the project. This will generate the application binary which can be used to run on Sitara processors.

2.1.8.1. Generating EtherCAT sources using the Patch file (Option #1)

  • Download Windows Patch Utility from gnuwin32 sourceforge. ( Note that this is not a TI tool - See licensing information page for more details)
  • Download Dos2Unix/Unix2Dos-Text file format converters from gnuwin32 sourceforge. ( Note that this is not a TI tool. See licensing information page for more details)
  • Extract the zip files to the Windows PC. Patch file utility(Patch.exe) and unix2dos.exe utility can be found in their bin folders.
  • Launch DOS Command prompt ( Start->Run->cmd).
  • CD to the folder [INSTALL-DIR]/third_party/protocols/ethercat_slave/patch which contains TI_ECAT.patch.
  • Execute unix2dos.exe as given below

[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe TI_ECAT.patch

  • CD to patch file utility bin folder.
  • Execute patch.exe as given below

patch.exe -i PATCH_FILE_NAME -d SOURCE_DIR

where PATCH_FILE is name of the patch file with full path and

SOURCE_DIR is Directory with full path where source files are present.

Example :
patch.exe -i [INSTALL-DIR]/third_party/protocols/ethercat_slave/patch/TI_ECAT.patch -d c:\SSC_V5i12\SlaveFiles\src

Note

Do NOT attempt to apply the TI_ECAT.patch to the sources generated by SSC tool described in the Option #2 below

2.1.8.2. Generating EtherCAT sources using Beckhoff SSC Tool (Option #2)

This configuration tool facilitates working with the Beckhoff ET9300 EtherCAT Slave Stack Code (SSC).It allows reducing the size of the EtherCAT slave stack code by removing unused code parts depending on the desired configuration.

This tool can be used to generate EtherCAT sources for TI Sitara SoCs . There is a method to generate EtherCAT stack code with TI specific changes using SSC and it is described below.

  1. Download EtherCAT stack version 5.12 from ETG website and extract it to a local folder. Please see application note for more details on SSC.
  2. Install SSC tool version 1.4.0.0.
  3. Click on “Import” button and select TI_[SOC]_1i0i7i0.xml located at [INSTALL-DIR]/third_party/protocols/ethercat_slave/patch.
  4. Make sure “Custom” is selected in the dialog box and “TI [SOC] Sample <Texas Instruments Incorporated>” is selected from the list.
  5. Set DC_SUPPORTED to 1 if not set.
  6. Save the project
  7. Click “Project->Create new Slave Files” - This will generate the ETherCAT Source files specific to the the selected TI device.
  8. The generated files can be found at the SSC tool project file location.
  9. Copy the generated files to [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/EcatStack/ and build the project.

Note

Please note that the TI_[SOC]_1i0i7i0.xml provided in the package are only for full mode application and might not work correctly when enabling CiA402_Device mode. Please use the patching approach (Option #1) for CiA402_Device mode.

2.1.8.3. Generating ESI Header file From ESI xml

The above given EtherCAT application is expected to be used against the ESI xml file given in esi folder.If the application should work with another ESI xml file, user will need to generate a corresponding ESI header file ( tiesc_eeprom.h ) and re-build the ethercat_slave_full application project with the generated .h file.

  • Generate the binary file equivalent to ESI xml file.

    • Configure TwinCAT as mentioned in TI_ESC slave setup with TwinCAT3
    • Click on the TI Box. Select EtherCAT Tab. Click on the “Advanced Settings” button.
    • Select ESC Access->E2PROM->Hex Editor. Select ‘Write to File’ and save the binary as a ”.bin” file.

    Note

    Please make sure that upload button is not clicked any time during this step. It will load the EEPROM data from TI ESC to TwinCAT memory.

  • Convert the binary file to header file using the bin2header.exe utility. This utility can be found in [INSTALL-DIR]/examples/tools/bin2header

    • Usage:
    bin2header.exe input_file output_file out_array_name
    • Example:
    bin2header.exe tiesc_eeprom.bin tiesc_eeprom.h tiesc_eeprom

  • Replace the existing file with new header file (tiesc_eeprom.h) to [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/[board]

  • Rebuild the application

2.1.9. Running EtherCAT Application in DC Mode

Following section shows how to run EtherCAT application in DC mode with TwinCAT master:

  1. Launch TwinCAT XAE Shell and discover all the slaves in slave chain. Multiple slaves are required to make use of distributed clocks. Here, we used two TI-ESCs in the chain.

  2. Choose DC Synchronization for all devices in the chain. Click on Box n (TIESC-*). Open the DC tab, and choose “DC-Synchron” option in Operation Mode. Do this for all slaves in the chain.

    ../../../_images/EtherCAT_Slave_DC_Mode1.PNG

  3. In Solution Explorer, go to TwinCAT project, Select SYSTEM > Real-Time. In the “Settings” tab, choose the desired Base Time. With compatible NIC cards, a base time of as low as 50 us can be chosen.

    ../../../_images/EtherCAT_Slave_DC_Mode_21.PNG

  4. Right-click ON SYSTEM > Tasks. Click “Add New Item” on the pop-up menu. Select “TwinCAT Image with Task” in the next dialog box. Type a name for the task, and choose OK.

    ../../../_images/EtherCAT_Slave_DC_Mode_31.PNG ../../../_images/EtherCAT_Slave_DC_Mode_41.PNG

  5. In the “Task” tab for the created task, select Auto Priority Management. Press OK in dialog box saying “Global Priority Management should be turned on”.

  6. Choose “Auto start” for the task. Choose 2 cycle ticks’ frequency for the task.

    ../../../_images/EtherCAT_Slave_DC_Mode_51.PNG

  7. Add an output variable to the task. Right-click on [Task name] > Outputs, and choose “Add New Item”. You may choose default options for the variable.

    ../../../_images/EtherCAT_Slave_DC_Mode_61.PNG

  8. Link the variable to an output for the last slave in the chain. Right-click on [Variable name], and choose “Change Link...”.

    ../../../_images/EtherCAT_Slave_DC_Mode_71.PNG

  9. Choose an output from the last slave. You may need to choose “All Types” in “Show Variable Types”.

    ../../../_images/EtherCAT_Slave_DC_Mode_81.PNG

  10. You can launch into Run mode by clicking the ethercat_slave_twincat_activate_configuration_logo “Activate Configuration” button on the toolbar.

  11. Choose Yes to generate mapping after modifying configuration, click on OK to “Activate Configuration?”, and Yes to Restart in RUN mode.


../../../_images/E2e1.jpg

For technical support, please post your questions at http://e2e.ti.com