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
Reference Documents¶
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.
- Demonstrating DDR-less EtherCAT Slave on AMIC110
- Demonstrating TI ESC SPI Mode DDR-less AMIC110 with C2000 EtherCAT Slave
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.
- Edit the file
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
- The valid values for first command line argument [SOC] are
- [PROCESSOR]
- The valid values for second command line argument [PROCESSOR] are
- arm - To generate a project specific to ARM core
- The valid values for second command line argument [PROCESSOR] are
- [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)
- The valid values for third command line argument [PROJECT_NAME]
to be used with EtherCAT slave installer package
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.
- For Simple Demo Application use ethercat_slave_demo as the command line argument
- 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¶
- 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.
- Copy the ESI file to <Drive>:\TwinCAT\3.1\Config\Io\EtherCAT
folder
- ESI file for EtherCAT Slave demo application is
[INSTALL-DIR]/examples/ethercat_slave/esi/TiEtherCATLib.xml
- ESI file for EtherCAT Slave full application is
[INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/esi/TI_ESC.xml
- ESI file for EtherCAT TI ESC SPI Mode (ASIC Mode) Slave
application is
TMDSECATCNCD379D EtherCAT slave (SPI).xml
available in ControlSUITE
- ESI file for EtherCAT Slave demo application is
- Start the TwinCAT XAE (VS2010)
- Create a new TwinCAT XAE project: File > New > Project > TwinCAT Project
- 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.
- 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).
- 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¶
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)
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.
A dialog will pop-up prompting Load I/O Devices, select Yes
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.
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.
- 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.
Figure 2 TwinCAT Status / Control Display
The user can control digital out LEDs using TwinCAT. Select TI Boxn(ti-esc)>DO Outputs > LED1-8 to control the output LEDs.
- The LEDs are set by selecting an LED N and then selecting the Online tab.
- The LED is turned on and off by selecting write and setting the value to 1 and 0 respectively.
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¶
The TI ESC SPI Interface applications (SPI Master and Slave mode) are added to provide EtherCAT support over SPI to non-EtherCAT devices.
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.
The package contains TI ESC SPI Master mode application for AM572x and TI ESC SPI Slave mode application for AMIC11x.
- 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.
- 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.
For the TI ESC SPI Mode projects, in the project build procedure the [PROJECT_NAME] need to be replaced in the final command with
- ecat_ti_esc_spi_master : For generating the TI ESC SPI Master Project
- ecat_ti_esc_spi_slave : For generating the TI ESC SPI Slave Project
Before uploading the applications, make the pin connections as shown in the image below
TI ESC SPI Mode Pin Map
To start the applications, first run the ‘ecat_ti_esc_spi_slave’ application and then run the ‘ecat_ti_esc_spi_master’ application
Constraints on the ET1100 SPI protocol supported by the TI ESC SPI Mode Slave Application on AMIC11x
- The Maximum SPI Baud rate currently supported is 6MHz
- Only the following ET1100 commands are supported
- ET1100_SPI_COMMAND_READ_WAIT -> 0x03
- ET1100_SPI_COMMAND_WRITE -> 0x04
- In case of Read command, 3 wait state bytes are required
- Delay required after every SPI transfer
- Read transfer -> 20us delay
- Write transfer -> 20us delay
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:
- EtherCAT Slave Package (version 01.00.07 or later)
- 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
- Generate the project files of the required application for AMIC11x or AMIC12x SoC using the Steps to generate Project files
- 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:
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.
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
Below is the detailed procedure:
- Open SSC Tools
- Go to Tools->EEPROM Programmer
- 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”
- Now in the Device Description drop down select “TIESC-001”
- 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¶
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:
- Open SSC Tools
- Go to Tools->EEPROM Programmer
- In EEPROM Programmer, go to File->Open. Here select the “TMDSECATCNCD379D EtherCAT slave (SPI).xml” ESI file from the controlSUITE
- Now in the Device Description drop down select “TMDSECATCNCD379D EtherCAT slave (SPI)”
- 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¶
[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.
- Download EtherCAT stack version 5.12 from ETG website and extract it to a local folder.
- Generate the patched EtherCAT Slave stack code source files using any one of the below mentioned methods
- Copy the patched Beckhoff source files (.c and .h) to
[INSTALL-DIR]/protocols/ethercat_slave/ecat_appl/EcatStack
- Generate CCS project following Steps to generate Project files
- Launch CCS and import ethercat_slave_full application project found
at the Project create directory (say,
[INSTALL-DIR]/protocols/ethercat_slave/projects
) to CCS - Define macros in ecat_appl\EcatStack\ecat_def.h as required for
your application.
- Ensure that TIESC_HW is set to 1
- For running default application, set TIESC_APPLICATION to 1 and CiA402_DEVICE to 0
- For running CiA402 application, set TIESC_APPLICATION to 0
and CiA402_DEVICE to 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.
- 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
SOURCE_DIR is Directory with full path where source files are present.
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)¶
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.
and K2G SoC. There is a method to generate EtherCAT stack code with TI specific changes using SSC and it is described below.
- 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.
- Install SSC tool version 1.4.0.0.
- Click on “Import” button and select TI_[SOC]_1i0i7i0.xml located at
[INSTALL-DIR]/third_party/protocols/ethercat_slave/patch
. - Make sure “Custom” is selected in the dialog box and “TI [SOC] Sample <Texas Instruments Incorporated>” is selected from the list.
- Set DC_SUPPORTED to 1 if not set.
- Save the project
- Click “Project->Create new Slave Files” - This will generate the ETherCAT Source files specific to the the selected TI device.
- The generated files can be found at the SSC tool project file location.
- 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 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 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 ``
“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)
- For RxPDO : If
RxPDO_CACHED
is set to 0 then it uses on-chip memory; if set to 1 it uses DDR memory - 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¶
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.
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.
4. Start TwinCat XAE (VS 2010) from start menu. Create new TwinCAT XAE Project (XML format).
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 > Show Realtime Ethernet Compatible Devices.<br>
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”.
7. Go to I/O > Devices. Right-click and select Scan. Press OK in the next dialog to start scanning for EtherCAT devices
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”
9. The TI device will be listed “Box n (TIESC-001)”. Press Yes to activate Free Run
10. Expand the box to see Process Data Inputs(PDI) and Outputs(PDO)
11. Right-click Box ‘’n’’ <RxPDO> 32Bit Output. Select Online Write.
12. Enter the value in hexadecimal format, where each bit in the LSB represents an output.
13. Changing the LED value will set/clear the appropriate LED
Archives¶
- Release 01.00.06
- Release 01.00.05
- Release 01.00.04
- Release 01.00.03
- Release 01.00.02
- Release 01.00.01
- Release 01.00.00
For technical support please post your questions at http://e2e.ti.com