PRU ICSS EtherCAT Slave User Guide

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.


Release 01.00.07

Released November 2018


What’s New

  • PRU-ICSS EtherCAT Slave Software (100M MII) support for AM654x SoC
  • CiA402 Drive Profile support for Single chip drive application
  • Bug Fixes

For detailed changes on the release, please check out Release notes

System Requirements

Supported Devices

  • AM572x IDK 1.3A/B
    • PRU-ICSS2 is used for validation [AM57x has 2 PRU-ICSS instances]
  • AM571x IDK 1.3A
  • AM437x IDK
  • AM335x ICEV2
  • K2G ICE
  • AMIC11x ICE
  • AMIC12x ICE
  • AM654x IDK

Component Version

The following is a list of tools bundled into the CCS installer. If you need to install CCS, see the CCS installation section

Component Version
CCS 8.1.0
Linaro GCC ARM Compiler gcc-arm-none-eabi-6-2017-q1-update
Linaro GCC ARM Compiler (aarch64) gcc-linaro-7.2.1-2017.11-i686-mingw32_aarch64-elf

This release requires Processor SDK RTOS, see Processor SDK Getting Started Guide |

Component Version
Processor SDK RTOS for AM57xx 5.1.0
Processor SDK RTOS for AM437x 5.1.0
Processor SDK RTOS for AM335x 5.1.0
Processor SDK RTOS for K2G 5.1.0
Processor SDK RTOS for AM65X 5.1.0

Details on Processor SDK RTOS component versions can be found here

Directory Structure

|   |--- docs

|       |---Industrial_Protocol_Package_Getting_Started_Guide.pdf

|       |---Industrial_Protocol_Package_Software_Developer_Guide.pdf

|       |---PRU_ICSS_EtherCAT.pdf

|       |---PRU_ICSS_EtherCAT_Release_Notes.pdf

|   |--- examples

|       |--- board

|           | --- common

|           | --- iceAM335x

|           | --- iceK2G

|           | --- idkAM437x

|           | --- idkAM571x

|           | --- idkAM572x

|           | --- idkAM65xx

|           | --- include

|           | --- osal

|       |--- ethercat_slave

|           | --- esi

|       |--- tools

|           | --- bin2header

|   |--- protocols

|       |--- ethercat_slave

|               |--- docs

|                       |--- doxygen

|               |--- ecat_appl

|                       |--- EcatStack

|                       |--- esi

|                       |--- iceAM335x

|                       |--- iceK2G

|                       |--- idkAM57x

|                       |--- idkAM437x

|                       |--- idkAM65xx

|               |--- firmware

|                       |--- v1.0

|                       |--- v2.0

|                       |--- v2.1

|                       |--- v2.2

|                       |--- g_v1.0

|               |--- include

|               |--- projects

|       |--- pdk_patches

|   |--- third_party

|       |--- protocols

|               |--- ethercat_slave

|                           |--- include

|                           |--- patch

|                           |--- stack_lib

Note

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


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.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.
  • On-chip Memory (DDRless) Execution of EtherCAT Slave Application
    • This section covers the steps needed to run the EtherCAT slave application entirely from on-chip memory on the AMIC11x ICE or AMIC12x ICE boards. It contains important instructions for patching the Processor SDK to build thumb mode binaries, flash partitioning, and configuring the location of binaries in device memory.
  • 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

Generating Project files

Steps to generate Project files

  • Setup the environment variables
    • Edit the file [INSTALL-DIR]/protocols/<protocol name>/projects/projectCreate.bat or .sh to align to the environment in your machine. All these paths should be accurate and mandatory; otherwise will cause errors.
      • CCS_INSTALL_DIR - Set the path where the recommended version of CCS is installed in user machine(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.

Note

Use the default path provided for CCS_WORKSPACE_LOC as a reference. The ‘user’ needs to be replaced by actual user account name in the PC

  • 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.bat)
  • 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/<protocol name>/projects
  • Run projectCreate.bat or projectCreate.sh. The batch file takes three mandatory command line arguments (The mandatory arguments are case sensitive!)

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

  • [SOC]
    • The valid values for first command line argument [SOC] are
      • AM571x - To generate a project specific to AM571x
      • AM572x - To generate a project specific to AM572x
      • AM437x - To generate a project specific to AM437x
      • AM335x - To generate a project specific to AM335x
      • AMIC11x - To generate a project specific to AMIC11x
      • AMIC12x - To generate a project specific to AMIC12x
      • K2G - To generate a project specific to K2G
      • AM65xx - To generate a project specific to AM65xx
  • [PROCESSOR]
    • The valid values for second command line argument [PROCESSOR] are
      • arm - To generate a project specific to ARM 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
      • ecat_ti_esc_spi_master - to generate EtherCAT TI ESC SPI Mode Master application project (supported only for AM572x)
      • ecat_ti_esc_spi_slave - to generate EtherCAT TI ESC SPI Mode Slave (ASIC Mode) application project (supported only for AMIC11x)
      • ethercat_slave_cia402 - to generate Single-Chip Motor-Control application through Standard CiA402 Drive Profile over EtherCAT (supported only for AM437x)

Note

Ensure that Code Composer Studio is not running when executing projectCreate.bat or projectCreate.sh. If not, the eclipsec may throw errors

  • Usage example 1 : projectCreate.bat AM572x arm ethercat_slave_demo
    • To generate the project files for EtherCAT slave demo application for AM572x ARM core by overwriting the project if it is already existing in PROJECT_CREATE_DIR\PROJECT_NAME_SOC_PROCESSOR
  • Usage example 2 : projectCreate.bat AM571x arm ethercat_slave_full
    • To generate the project files for EtherCAT slave full application for AM571x ARM core by overwriting the project if it is already existing in PROJECT_CREATE_DIR\PROJECT_NAME_SOC_PROCESSOR

Note

If the project create is successful, the generated project files will be found in [INSTALL-DIR]/protocols/<protocol name>/projects/PROJECT_NAME_SOC_PROCESSOR


More info

The projectCreate.bat or.sh utilizes the project arguments provided in [INSTALL-DIR]/protocols/<protocol name>/projects/ccsproject_args to generate the project file



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. Additional details on TwinCAT configuration can be found at here.

Note

To use PRU-ICSS1 on the AM571x IDK or K2G ICE, the #define PRUICSS_INSTANCE need to set to PRUICSS_INSTANCE_ONE in the [INSTALL-DIR]/protocols/ethercat_slave/include/tiesc_soc.h file

Note

Additional RTSC cfg files for the projects are included in the package for each SoC with System Analyzer and other debug features enabled by default. These files can be found at [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/[soc]_app_debug.cfg. Detailed tutorials on using System Analyzer with Code Composer Studio can be found here



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 (VS2010)
  4. Create a new TwinCAT XAE project: File > New > Project > TwinCAT Project
  5. Goto 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 . Note, please always check 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 CAT5 Ethernet cable from TwinCAT PC to EtherCAT IN/Port0 of PRU-ICSS 2 on AM572x IDK. 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).
    1. Below table gives details on the default PRU-ICSS instance on all the supported ICE and IDK Boards
SoC / Board PRU-ICSS Instance Available Default PRU-ICSS Instance
AM335x / AM335x ICEv2 AMIC11x / AMIC11x ICE PRU-ICSS0 PRU-ICSS0
AM437x / AM437x IDK AMIC12x / AM437x IDK PRU-ICSS0, PRU-ICSS1 PRU-ICSS1
AM572x / AM572x IDK AM571x / AM571x IDK PRU-ICSS1, PRU-ICSS2 PRU-ICSS2
K2G / K2G ICE PRU-ICSS0, PRU-ICSS1 PRU-ICSS1

Note

For detailed instructions on K2G ICE configuration with TwinCAT please refer to Configuring TwinCAT for K2GICE EtherCAT Slave


Starting EtherCAT application

  1. In Solution Explorer go to your new TwinCAT project > I/0 > right click Device1(EtherCAT)> select Scan Boxes… If Scan Boxes is grayed out then select TWINCAT > Restart TwinCAT (Config Mode)

  2. TI Boxn(ti-esc) will be detected automatically. 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.

  3. A dialog will pop-up prompting Load I/O Devices, select Yes

  4. Next dialog asks confirmation to Activate Free Run - select Yes. This will put TI ESC into OP mode. Alternatively, you can use “Toggle Free Run State” bottom.

  5. The application should show digital out 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. 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. If another mode or errors are shown the interface can be reinitialized by performing Step 7.

    1. On startup, the application will set digital out LEDs 2, 4, 6 and 7 on (For AMIC11x LEDs 2 and 5 are on). This indicates that slave is up and in the INIT state.
    indsw/EtherCAT_Slave/01_00_07/../../../images/Twincat_Device.jpg

    Figure 2 TwinCAT Status / Control Display

  6. The user can control digital out LEDs using TwinCAT. Select TI Boxn(ti-esc)>DO Outputs > LED1-8 to control the output LEDs.

    1. The LEDs are set by selecting an LED N and then selecting the Online tab.
    2. The LED is turned on and off by selecting write and setting the value to 1 and 0 respectively.
    indsw/EtherCAT_Slave/01_00_07/../../../images/Twincat_LED.jpg

    Figure 3 TwinCAT LED Control Display

For more information, Please see Configuring TwinCAT for TI EtherCAT Slave

TI ESC SPI Interface to Support ASIC mode for EtherCAT

TI ESC SPI Slave (ASIC Mode) on AMIC11x with AM572x

  1. The TI ESC SPI Interface applications (SPI Master and Slave mode) are added to provide EtherCAT support over SPI to non-EtherCAT devices.

  2. These applications are a demonstration of running the existing Beckhoff SSC stack on a MCU/MPU that communicates over SPI with a Sitara/AMIC110 device running the EtherCAT firmware. This will help to extend EtherCAT functionality to non-EtherCAT devices without replacing the existing MCU/MPU.

  3. The package contains TI ESC SPI Master mode application for AM572x and TI ESC SPI Slave mode application for AMIC11x.

    1. TI ESC SPI Slave Mode : This application runs the EtherCAT firmware and it responds to the ET1100 compatible SPI requests from the Master application running the Beckhoff SSC stack. As EtherCAT stack and firmware only communicate via memory access, the Master sends only memory read and write requests over SPI and the Slave executes and responds to the requests. PDI and SYNC signals from firmware are redirected over GPIO pins from the Slave to the Master. The SPI Slave application doesn’t contains the Beckhoff SSC stack.
    2. TI ESC SPI Master Mode : This application runs the Beckhoff SSC stack and doesn’t contains the EtherCAT firmware. The Master application communicates with the Slave application over SPI.

  4. For the TI ESC SPI Mode projects, in the project build procedure the [PROJECT_NAME] need to be replaced in the final command with

    1. ecat_ti_esc_spi_master : For generating the TI ESC SPI Master Project
    2. ecat_ti_esc_spi_slave : For generating the TI ESC SPI Slave Project

  5. Before uploading the applications, make the pin connections as shown in the image below

    ../../../_images/Et110_mode_pin_map.png

    TI ESC SPI Mode Pin Map

  6. To start the applications, first run the ‘ecat_ti_esc_spi_slave’ application and then run the ‘ecat_ti_esc_spi_master’ application

  7. Constraints on the ET1100 SPI protocol supported by the TI ESC SPI Mode Slave Application on AMIC11x

    1. The Maximum SPI Baud rate currently supported is 6MHz
    2. Only the following ET1100 commands are supported
      1. ET1100_SPI_COMMAND_READ_WAIT -> 0x03
      2. ET1100_SPI_COMMAND_WRITE -> 0x04
    3. In case of Read command, 3 wait state bytes are required
    4. Delay required after every SPI transfer
      1. Read transfer -> 20us delay
      2. Write transfer -> 20us delay

TI ESC SPI Slave (ASIC Mode) on AMIC11x with C2000

A detailed description of running TI ESC SPI Slave mode on AMIC11x along with C2000 running the EtherCAT Slave Stack can be found here

Single-Chip Motor-Control application

The Single-Chip Motor-Control application uses EtherCAT as the industrial communication protocol, and demonstrates single-chip motor control using the standard CiA402 Drive profile over an EtherCAT network. The IEC standard of CiA 402 specifies a set of generic default PDOs available to all drives, as well as a set of specific default PDOs applicable only to a specific class of drives such as servo drives, frequency inverters, or stepper motors. IEC 61800-7-201 and IEC 61800-7-301 specify the CiA 402 drive profile, which is mapped to EtherCAT. The EtherCAT Slave Stack Code (SSC) provides a sample implementation of the CiA 402 drive profile. In this application, the default implementation from the SSC is used for motor control demonstration. More details on the CiA 402 Drive profile and the stack implementation can be found in EtherCAT Slave Stack Code Application Note ET9300 and ETG6010 CiA402 Implementation Directive.

The application demonstrates a sensored three-phase, sensored field oriented control (FOC) for a single PMSM using the on-chip AM437x ADCs. The EnDat 2.2 master interface provides position information with a EnDAT encoder attached to the motor. The motor-control application has been validated using a permanent-magnet motor (BLY171D-24V-4000, Anaheim Automation). The motor can be coupled to an EnDat 2.2 encoder (ROQ 437, Heidenhain) to provide position information to the FOC algorithm. The IDK uses the three terminals of J17 to provide the motor drive.

To build and run the single-chip motor drive application, install the following the SDKs:

  1. EtherCAT Slave Package (version 01.00.07 or later)
  2. Industrial Drives Package (version 01.00.02 or later)

For the single-chip drive application, the “DRIVES_SDK_INSTALL_PATH” variable must also be updated in the projectCreate.sh/.bat script of EtherCAT Slave package to point to the installation directory of Industrial Drives Package. Provide the “Project_Name” argument as “ethercat_slave_cia402” to the projectCreate script to generate the single-chip drive application files. The final command will look like:

projectCreate.sh/.bat AM437x arm ethercat_slave_cia402

Detailed description on the application and setup can be found in the Single Chip Drive for Industrial Communications and Motor Control TI Design (TIDEP0025)


On-chip Memory (DDRless) Execution of EtherCAT Slave Application

EtherCAT Slave Package provides support for application execution using only on-chip memory i.e. DDRless on AMIC11x and AMIC12x SoCs. Both the full mode application and demo mode application support on-chip memory execution. Also the TI ESC SPI Slave mode (ASIC mode) on AMIC11x supports on-chip memory execution. To build any of the above application in on-chip memory execution mode follow the below process

  1. Generate the project files of the required application for AMIC11x or AMIC12x SoC using the Steps to generate Project files
  2. Import the generated project into CCS and select AMIC12x_release or AMIC11x_release as the build configuration, by default release configuration is pre-configured to compile in on-chip memory execution mode

On-chip Memory (DDRless) Execution on AMIC12x ICE

On AMIC12x in On-chip Memory (DDRless) execution setup, the EtherCAT Slave application loads and runs out of L2_cache in SRAM mode and OCMC memory. To build any AMIC12x EtherCAT application in DDRless mode, the AMIC12x_release configuration has to be used. The generated application needs to be used along with a modified SBL or updated Gel files. AMIC12x on-chip Memory execution supports using mmcsd, QSPI Flash and JTAG to load the application.

Modifying SBL for AMIC12x on-chip Memory Execution

The AMIC12x on-chip memory application utilizes the L2_cache as SRAM. By default, the SBL configures the L2_cache as a cache memory and not SRAM. As we need the memory to be configured as SRAM before starting the application, the SBL needs to be modified for the same. A patch available in the EtherCAT Slave Package for modifying the SBL source at this path [INSTALL-DIR]/protocols/pdk_patches/04.03.00/AMIC12x_DDR-less_MLO.patch. The SBL needs to be rebuilt after applying the patch. This patch will modify both the mmcsd and QSPI bootloaders. Use the below command to apply the patch

patch.exe -i [INSTALL-DIR]/protocols/pdk_patches/04.03.00/AMIC12x_DDR-less_MLO.patch -d [PDK_INSTALL_PATH]/pdk_am437x_1_0_10/packages -p0

Details on patching and rebuilding the Processor SDK can be found at Processor SDK Patching and Rebuilding. SBL is built under the target starterware.

Modifying Gel files for AMIC12x on-chip Memory Execution

For the same reason mentioned above we also need to modify the Gel files before upload the AMIC12x on-chip memory application via JTAG. Please add the below lines to the function AM43xx_IDK_EVM_Initialization() in the file ccsv7/ccs_base/emulation/boards/idk_am437x/gel/AM437x_EVMs.gel.

GEL_TextOut("Enabling L2 as SRAM...  \n");
*((unsigned int*) 0x44E10654)      =  4;
*((unsigned int*) 0x44E101E0)      =  0x10000;
GEL_TextOut("Enabled L2 as SRAM...  \n");

Note

The modified SBL and Gel files will NOT work with DDR based cache enabled AMIC12x or AM437x applications. The above mentioned modifications need to be reverted back if DDR-less mode is not used


On-chip Memory (DDRless) Execution on AMIC11x ICE

On AMIC11x in On-chip Memory (DDRless) execution setup, the EtherCAT Slave application loads and runs out of OCMC memory and utilizes M3 internal and shared memory. To build any AMIC11x EtherCAT application in DDRless mode, the AMIC11x_release configuration has to be used. The generated application needs to be flashed on the SPI Flash memory of the board, along with a special SBL file available from Processor SDK. This implementation of the EtherCAT Slave application lays out the memory map of the application and the bootloader as described in the figure below:

../../../_images/DDRlessAPP.PNG

Patching Processor SDK for Thumb Mode binaries

For DDRless application to build, it is critical that Processor SDK is build in Thumb Mode. A patch file has been included in the package for the same. This file can be found at [INSTALL-DIR]/protocols/pdk_patches/04.03.00/AM335x_PDK_thumb_mode.patch. After applying this package the Processor SDK needs to be cleaned and rebuilt.

Flash Partitioning

During normal operation, users are required to flash SBL in 0x000000 and App at 0x20000. In DDRless mode, the SBL has to load additional binaries to PRU0 IRAM and PRU1 IRAM and store TIESC EEEPROM, the following flash memory map was set to flash the application binaries.

../../../_images/Flash_partition_updated.png

Flashing application binaries

The SBL and Application can be flashed to the SPI flash as described Booting Via McSPI

Configuring location of binaries in device memory

The load location for binaries loaded by the bootloader are configured by providing the location in the TI IMAGE header appended to these binaries. The prebuilt ti image binaries for ecat_frame_handler and ecat_host_interface can be found at [INSTALL-DIR]/protocols/ethercat_slave/firmware/v1.0/. Pre-built binary of tiesc_eeprom can be found at path [INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/iceAM335x/

The process of generating the binaries by providing the device memory location and appending the TI IMAGE header to the binary is described below:

Converting PRU firmware to TI image format:

Converting PRU0 firmware (ecat_frame_handler)

tiimage.exe 0x4a334000 NONE ecat_frame_handler.bin ecat_frame_handler_ti.bin

Converting PRU1 firmware (ecat_host_interface)

tiimage.exe 0x4a338000 NONE ecat_host_interface.bin ecat_host_interface_ti.bin

Converting TIESC EEPROM Data (tiesc_eeprom)

tiimage.exe 0x4030F400 NONE tiesc_eeprom.bin tiesc_eeprom_ti.bin

ecat_frame_handler.bin and ecat_host_interface.bin are available at [IA_SDK_HOME]\protocols\ethercat_slave\firmware\v1.0


tiesc_eeprom.bin can be generated from ESI file using SSC Tool.

Below is the detailed procedure:

  1. Open SSC Tools
  2. Go to Tools->EEPROM Programmer
  3. In EEPROM Programmer, go to File->Open. Here select the TI_ESC.xml ESI file from the path “[IA_SDK_HOME]\protocols\ethercat_slave\ecat_appl\esi”
  4. Now in the Device Description drop down select “TIESC-001”
  5. File->Save as. Select “Save as type” as “binary (*.bin)”. Provide the path and Save.

Configuring offset of binaries in SPI flash

After the TI image binaries are created, users are required to program the binaries to the SPI flash using the flash writer from <PDK_INSTALL_DIR\packages\ti\starterware\tools\flash_writer\spi_flash_writer_AM335X.out onto the EVM. For out of the box user experience the three additional binaries need to be flashed at the following offsets.


Binary Name Offset
ecat_frame_handler_ti.bin 0x19000
ecat_host_interface_ti.bin 0x14000
tiesc_eeprom_ti.bin 0x10000

SBL for DDRless Execution

DDRless execution requires a special SBL which loads the firmware and

eeprom data along with the application. | More details on building the bootloader for DDR-less execution on AMIC11x can be found here.

TI ESC SPI Slave (ASIC mode) on AMIC11x with On-chip memory execution

The process mentioned in On-chip Memory (DDRless) Execution on AMIC11x ICE is also applicable for TI ESC SPI Slave (ASIC mode) on AMIC11x. The only difference is the eeprom binary to be flashed is different for ASIC mode. The ESI file “TMDSECATCNCD379D EtherCAT slave (SPI).xml” used to be generate the eeprom binary is available in the controlSUITE.

tiesc_eeprom.bin for ASIC mode can be generated from the ESI file using SSC Tool. Below is the detailed procedure:

  1. Open SSC Tools
  2. Go to Tools->EEPROM Programmer
  3. In EEPROM Programmer, go to File->Open. Here select the “TMDSECATCNCD379D EtherCAT slave (SPI).xml” ESI file from the controlSUITE
  4. Now in the Device Description drop down select “TMDSECATCNCD379D EtherCAT slave (SPI)”
  5. File->Save as. Select “Save as type” as “binary (*.bin)”. Provide the path and Save.

The load location needs to be configured in the generated eeprom binary. Please follow the steps mentioned in Configuring location of binaries in device memory for the same.


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.

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

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

and K2G SoC. 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.

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.

Steps for generating ESI header file is given below.
  • Generate the binary file equilant to ESI xml file. Pease see Generating EEPROM binary.
  • 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 ‘binary_filename’ ‘header_filename’
Example:
bin2header.exe “C:\Documents and Settings\user\Desktop\Box1.bin”

“C:\Documents and Settings\user\Desktop\tiesc_eeprom.h” br>

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

Enhanced Process Data Interface with EDMA support (only supported on AM4377/9)

EtherCAT Slave package includes an updated way to access to SyncManager Process Data buffers from application side. Significant reduction in access latency is observed with this mode. This uses the EDMA IP in Sitara devices to offload the data buffer copy from the CPU and currently only supported on AM4377/9 SoCs. To enable this mode, the macro EDMA_LATENCY_ENHANCEMENT must be defined in the project. This can be done by adding this macro to the Project Properties->Build->GNU Compiler->Symbols->Define Symbols option. Once enabled, the application and firmware switches to using EDMA for buffer transfer.

Memory location of Buffer in application

The access latency is affected by the placement of buffer in the memory (eg:DDR, on-chip etc.). For the best results, please follow the below guidelines:

Function Buffer Size Memory Location
Read >10 bytes DDR (cached)
Read <=10 bytes on-chip Memory (non-cached)
Write any size on-chip Memory (non-cached)

The switching between DDR and on-chip memory of buffer is handled by the following macros (defined in tiescbsp.h)

  1. For RxPDO : If RxPDO_CACHED is set to 0 then it uses on-chip memory; if set to 1 it uses DDR memory
  2. For TxPDO : If TxPDO_CACHED is set to 0 then it uses on-chip memory; if set to 1 it uses DDR memory

Improvement Results

Read and write access latency for sync manager buffers in Process Data was measure for this benchmarking. The below improvements are measured using the maximum access latency recorded on AM437x IDK.

Process Data action Max time in legacy application Max time in Enhanced application Improvement Buffer Location
Read 253 bytes 25.4 µs 3.8 µs 6.5x DDR (cached)
Write 263 bytes 6.7 µs 1.9 µs 3.5x onChip RAM (non-Cached)
Read 5 bytes 1.9 µs 1.2 µs 1.5x onChip RAM (non-Cached)
Write 7 bytes 2.4 µs 0.7 µs 3x onChip RAM (non-Cached)

Using K2GICE EtherCAT Slave with TwinCAT 3

indsw/EtherCAT_Slave/01_00_07/../../../images/K2G_ICE-beta-web-5.jpg

Using K2GICE EtherCAT Slave with TwinCAT 3

Hardware setup

  • Connect cable between compatible Ethernet controller on PC and port on K2GICE EVM. A list of compatible NICs can be found on Beckhoff Information System website .Note that this is a mandatory hardware requirement when using TwinCAT 3.
  • Connect 24V to the board
  • Power up K2GICE EVM

TwinCAT Software setup

  • Install TwinCAT (Evaluation version is available for download from TWINCAT3 Download website . Select PLC mode for installation and check the IO drivers box
  • EtherCAT Slave Demo Application: Copy {EtherCAT_package_install_path}/examples/ethercat_slave/esi/TiEtherCATLib.xml to <Drive>:/TwinCAT/Io/EtherCAT folder. If you are using TwinCAT 3.1, the folder path is <Drive>:/TwinCAT/3.1/Config/Io/EtherCAT
  • EtherCAT Slave Full Mode Application: Copy {EtherCAT_package_install_path}/protocols/ethercat_slave/ecat_appl/esi/TI_ESC.xml to <Drive>:/TwinCAT/Io/EtherCAT folder. If you are using TwinCAT 3.1, the folder path is <Drive>:/TwinCAT/3.1/Config/Io/EtherCAT

Setup For EtherCAT Operation

Note: The default configuration of the EtherCAT application uses ICSS2 and J8 - this is described in the steps below. The alternative configuration of the EtherCAT application uses ICSS1 and J9.

1. Connect the Ethernet cable between K2GICE EtherCAT IN/Port0 (J8, lower RJ-45 port) and the PC with the TwinCAT installation. If you have multiple EVMs in chain, please connect from EtherCAT OUT/Port1 (J8, upper RJ-45 port) to IN/Port0 of the next EVM. For last EVM in chain, OUT/Port1 is left open.

indsw/EtherCAT_Slave/01_00_07/../../../images/K2G_ICE-beta-web-6-j8j9.jpg

2. Power up the K2GICE EVM board with a 24V power supply.

3. Observe the LEDs for a pattern to confirm that EtherCAT application has started. Observe also the OLED display with a text string.

indsw/EtherCAT_Slave/01_00_07/../../../images/K2G_ICE-beta-web-1-LEDs.jpg

4. Start TwinCat XAE (VS 2010) from start menu. Create new TwinCAT XAE Project (XML format).

indsw/EtherCAT_Slave/01_00_07/../../../images/TwinCATNewproject.jpg indsw/EtherCAT_Slave/01_00_07/../../../images/Twincatxaeproject.jpg

5. For the first time only you need to set the PC’s Ethernet port, which is used as the EtherCAT port. Go to TwinCAT &gt; Show Realtime Ethernet Compatible Devices.<br>

indsw/EtherCAT_Slave/01_00_07/../../../images/Show_compatible_devices.jpg

6. Select the Ethernet port from the list of compatible devices, and press Install. This will install a Beckhoff EtherCAT driver. Once installed, the Ethernet port will show up in “Installed and ready to use devices”.

indsw/EtherCAT_Slave/01_00_07/../../../images/List_of_devices.jpg

7. Go to I/O &gt; Devices. Right-click and select Scan. Press OK in the next dialog to start scanning for EtherCAT devices

indsw/EtherCAT_Slave/01_00_07/../../../images/Scandevices.jpg

8. 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”

indsw/EtherCAT_Slave/01_00_07/../../../images/Iodevicesfound.jpg

9. The TI device will be listed “Box n (TIESC-001)”. Press Yes to activate Free Run

indsw/EtherCAT_Slave/01_00_07/../../../images/Activatefreerun.jpg

10. Expand the box to see Process Data Inputs(PDI) and Outputs(PDO)

11. Right-click Box ‘’n’’ <RxPDO> 32Bit Output. Select Online Write.

indsw/EtherCAT_Slave/01_00_07/../../../images/Onlinewrite.jpg

12. Enter the value in hexadecimal format, where each bit in the LSB represents an output.

indsw/EtherCAT_Slave/01_00_07/../../../images/Setvaluedialog.jpg

13. Changing the LED value will set/clear the appropriate LED

indsw/EtherCAT_Slave/01_00_07/../../../images/K2G_ICE-beta-web-1-LEDs.jpg