AM335x SYSBIOS Industrial SDK 01.01.00.08 User Guide

Content is no longer maintained and is being kept for reference only!

AM335x SYSBIOS Industrial SDK 01.01.00.08 User Guide

Revision History

Revision	Date	Description
1.0	26-Mar-2015	Created initial version of the document

AM335x Industrial SDK Introduction

The SYSBIOS-based software development kit (SDK) for industrial communications is designed for the Sitara AM335x ARM Cortex-A8 microprocessor family to enable customers add real-time industrial communications easily and quickly to their system. By making all the basic system software components immediately available, the Kit allows developers to focus on their application code, where they can add the most differentiation. Optimized to support real-time industrial communications protocols such as EtherCAT, Profibus, Profinet, Ethernet/IP and many others, the SDK includes a real-time, low-footprint SYSBIOS kernel with boot loader and sample industrial applications to get started quickly.

The SYSBIOS Industrial SDK for AM335x combines all the software components and tools needed to begin development of SYS/BIOS-based applications on the ARM. The SDK supports AM335x IDK and ICE (V1/V2) hardware platforms and includes the following

• Open source SYS/BIOS Real Time Operating System (RTOS)
• Bootloader for Sitara AM3359 Industrial Development Kit (IDK) and Industrial Communication Engine (ICE) with support to boot from various peripherals
• Library of peripheral drivers integrated with SYSBIOS supporting both IDK and ICE
• Sample applications demonstrating peripheral use cases for both IDK and ICE
• Code Composer Studio integrated development environment (IDE) v.6
• Sample industrial input/output applications over communication protocols such as EtherCAT, PROFIBUS, EtherNet/IP, PROFINET and other Ethernet and serial based Fieldbus Industrial Ethernet protocols
• Evaluation versions of protocol stacks for industrial communications such as EtherCAT, PROFIBUS, EtherNet/IP, PROFINET and many others to facilitate software development

NOTE 

The Industrial SDK has gone through a series of modifications in between release 1.1.0.1 and 1.1.0.3. These changes are noted in here

The Industrial SDK is supported on IDK and ICE (V1/V2) development platforms.

A high level block diagram of AM335x IDK is given below.

A high level block diagram of AM335x ICE V1 is given below.

A high level block diagram of AM335x ICE V2 is given below.

Reference Documents

• AM335x Industrial SDK Getting Started Guide
• AM335x Industrial SDK 1.1.0.8 Release notes
• SYS/BIOS Getting Started Guide
• SYS/BIOS User Guide
• StarterWare Getting Started Guide
• StarerWare User Guide
• NDK Driver API Guide
• ICSS Switch Driver API Guide
• Ethernet/IP Driver API Guide
• Profinet Driver API Guide
• Ethercat Driver API Guide

SDK Directory Structure

|--- sdk

|   |--- docs

|       |---AM335x Industrial SDK User Guide.pdf

|       |---AM335x Industrial SDK Release Notes.pdf

|       |---AM335x Industrial SDK Getting Started Guide.pdf

|   |--- examples

|       |--- enetLwip_sysbios

|       |--- ethercat_slave

|           | --- esi

|       |--- ethernetip_adapter

|           |--- stc

|       |--- i2c_led

|       |--- profibus_slave

|           |--- GSD

|           |--- APP

|           |--- include

|       |--- profinet_slave

|           |--- GSD

|           |--- snmp

|       |--- uart_echo

|   |--- os_drivers

|       |--- include

|       |--- lib

|       |--- src

|   |--- platform

|       |--- am335x

|           |--- include

|           |--- lib

|           |--- src

|   |--- protocols

|       |--- ethercat_slave

|           |--- docs

|           |--- ecat_appl

|               |--- esi

|               |--- patch

|               |--- EcatStack

|       |--- ethernetip_adapter

|           |--- drivers

|           |--- eds

|           |--- firmware

|           |--- include

|           |--- stack_lib

|       |--- profibus_slave

|           |--- docs

|           |--- firmware

|           |--- include

|           |--- stack_lib

|       |--- profinet_slave

|           |--- drivers

|           |--- firmware

|           |--- include

|           |--- stack_lib

|       |--- snmp

|           |--- docs

|           |--- drivers

|           |--- include

|           |--- snmp_core

|           |--- stack_lib

|   |--- starterware

|   |--- tools

|       |--- bin2header

|       |--- flashing tools

|       |--- gel

|       |--- post_build

docs - This folder contains pdf version of Release Notes, User guide and Getting Started guide

examples - This folder contains examples, their project files, source and include files. Users can build the application in CCS using these files. Please see the Getting Started Guide for details on building the application

os_drivers - This folder contains source code and include files for SYS/BIOS driver for AM335x and a pre-built library.

platform - This contains the EVM specific initialization code which is not provided by StarterWare. This code sets up the EVM specifics like pinmux, IO expanders, GPIOs and similar board specific stuff that shall enable proper execution of the applications.

protocols - This folder contains supported industrial automation protocol libraries and/or source codes and their project files.

starterware - This contains StarterWare code which provides Device Abstraction Layer libraries and peripheral/board level sample/demo examples that demonstrate the capabilities of the peripherals on a no_OS platform. See StarterWare

tools - This contains tools supporting application development. For eg GEL files, SPI Flashing tool for ICE and post-build script.

System Requirements

Hardware

• AM335x IDK / AM335x ICE (V1/V2)
• Windows Host Machine with minimum 2GB RAM
• SD Card for IDK / Micro SD Card for ICE
• XDS 560/510 Class Emulators for debugging on IDK

Software 

• Code Composer Studio version CCS 6.0.0.00040
  
• SYSBIOS 6.41.04.54 Real Time Operating System
• XDC 3.30.06.67
• Compiler version TI v5.1.12
• Network Development Kit (NDK) 2.24.01.18
• Serial console terminal application (like Teraterm, minicom, HyperTerminal)

NOTE 1

• To run on CCSv6, make sure you refract the project after importing it

1. Right click on imported project and select Refactor Option
   
2. Select Upgrade RTSC Product Versions
   

This will update the RTSC components to version compatible with CCS6.
NOTE 2

• On CCSv5.5, please make sure you update the Compiler to TIv5.1.5(or above). This is important as the libraries provided in SDK are build using this compiler and not upgrading would result in linker errors.

SDK Setup

SDK setup will install following items in the machine.

• SDK Source files, CCS project files, pre-built libraries and documents

Installation process will create an environment variable called IA_SDK_HOME which will be set to location where the sdk is installed. This variable is used by sdk examples for include and library paths. IA_SDK_HOME is a string varable containing the path to the am335x_sysbios_ind_sdk_1.1.0.7/sdk subdirectory. This varable can also be defined in the CCS project properties.

Pre-Built Binaries and Libraries

The SDK installation comes with following pre-built libraries. These libraries can be used to build user applications quickly.

• am335x_platform.lib   -  Platform specific implementations which are not provided by StarterWare 
  

                                        SDK Path - $(IA_SDK_HOME)\platform\am335x\lib

• ecat_slave_stack.lib   -   EtherCAT Slave Stack library including PRU Firmwares

                                        SDK Path - $(IA_SDK_HOME)\protocols\ethercat_slave\stack_lib

• ethernetip_stack.lib    -  EtherNet/IP Slave stack library
  

                                         SDK Path - $(IA_SDK_HOME)\protocols\ethernetip_adapter\stack_lib

• profibus.lib                -  Profibus Slave stack library
  

                                        SDK Path - $(IA_SDK_HOME)\protocols\profibus_slave\stack_lib

• profinet_slave_stack.lib       -  Profinet Slave stack library
  

                                        SDK Path - $(IA_SDK_HOME)\protocols\profinet_slave\stack_lib

• snmp_core.lib       -  SNMP core stack library
  

                                        SDK Path - $(IA_SDK_HOME)\protocols\snmp\stack_lib

• sys_bios_driver.lib     -  SYS/BIOS specific implementation for accessing peripheral devices and EVM functionality

                                        SDK Path - $(IA_SDK_HOME)\os_drivers\lib

• drivers.lib                  -  StarterWare library for peripheral devices 

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\drivers

• platform.lib               -  Starterware EVM specific initialization library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\evmAM335x\platform

• mmcsd.lib                 -  Starterware MMC SD Card library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\mmcsdlib

• utils.lib                      -  StarterWare Utils library

                                         SDK Path - $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\utils

• lwip_static.lib            -  LightWeight TCP/IP stack library

                                         SDK Path - $(IA_SDK_HOME)\starterware\third_party\lwip-1.4.0\lib

The SDK does not include any pre-built binaries, however binaries generated using the SDK examples (given below) can be downloaded separately. All pre-built binaries except bootloader are board independent. Please see release notes for download link.

• enetLwip_sysbios - Sample application demonstrating Ethernet and TCP/IP functionality, using lwip as TCP/IP stack and CPSW ethernet interface.
• ethercat - Sample application demonstrating EtherCAT slave functionality.
• ethernetip_adapter - Sample application demonstrating EtherNet/IP adapter functionality, using Molex EtherNet/IP stack and supporting CPSW and ICSS ethernet switch interfaces.
• i2c_led - Sample application demonstrating LED toggling on the board.
• profibus_slave - Sample application demonstrating PROFIBUS slave functionality.
• profinet_slave - Sample application demonstrating PROFINET slave functionality.
• uartecho - Sample application demonstrating UART communication.

SYS/BIOS Driver

The AM335x SDK provides a driver library for accessing device peripheral modules from a SYS/BIOS application. This driver is basically an abstraction of StarterWare libraries along with SYS/BIOS OS specific implementation. Currently, this driver supports GPIO, I2C, UART, and McSPI module access plus the CPSW and ICSS NDK drivers. Other modules will be added to this library in future releases. This library supports both ICE and IDK.

Bootloader

The Starterware AM335X provides a simple bootloader, which can be copied to an MMCSD card or flashed to SPI/NOR flash depending up on board, which after a power-on-reset can bootstrap the board. Additionally, the SPI/SD card bootloader can load an application from the MMCSD card/SPI Flash to DDR or Internal RAM and transfer the control to the application. This can be used to provide a turnkey out-of-box solution for function demonstration.

Bootloader for IDK

Upon board power on, the RBL [Read Only Memory BootLoader], residing in the ROM of the AM335X kick starts. The RBL checks the boot mode setting (which should be MMCSD boot mode ) and depending upon the boot mode setting it copies boot loader from MMCSD card. The RBL requires boot loader to be named as "mlo". RBL copies the boot loader to internal memory and gives control to it. The Boot loader initializes PLL0 and PLL1 for all devices and then it initializes DDR. Once all the initialization is done, it copies the application from MMCSD card to the DDR and transfers the control to the application. The application starts to executing from DDR.

Bootloader for ICE (V1/V2)

Upon board power on, the RBL, residing in the ROM of the AM335X kick starts. The RBL checks for the boot mode settings(SYSBOOT) and depending on the settings, executes NOR bootloader or SPI bootloader or MMC/SD bootloader.

The SPI and MMC/SD boot loader looks for application (named as "app") in MicroSD card. If an application is found on the SD card, the boot loader loads that into DDR/Internal RAM and transfers control to it. Otherwise, boot loader loads the application from SPI flash to DDR and transfers control to it.
The SPI bootloader supports fast boot mode. Turbo mode is enabled in McSPI controller to copy application from SPI flash to DDR (the application binary should be in SPI flash). The Fast boot bootloader reduces the boot time of Ethernet/IP application from 3.006s to 114 ms. Information on building the SPI Bootloader in fast boot mode is provided in "Building Bootloader" section.

The NOR boot loader looks for an application(named as "app") on the MicroSD card. If it is found on the SD card, the boot loader loads that into DDR/Internal RAM and transfers control to it. Otherwise, boot loader looks for a valid image in every 64KB offset in NOR flash. If a valid image is found in the NOR flash, bootloader will transfer control to it.

Setting boot modes on ICE V1

The boot mode on ICE V1 boards (Rev A2) can be altered by connecting/disconnecting jumper on J10 pins.

• If the jumper is not connected on J10, the RBL will load the bootloader from SPI flash and execute it.
• If a jumper is connected between pin 1 & 2 on J10, the RBL will first check for valid boot image in NOR flash sector 0 and if it finds an image, the RBL will execute it. Otherwise, the RBL will load and execute SPI flash bootloader.

Setting boot modes on ICE V2

The boot mode on ICE V2 boards can be altered by connecting/disconnecting jumper on J5 pins. 

• If the jumper is not connected on J5, RBL will load the bootloader from SPI Flash or MMC/SD card and execute it. 
• If a jumper is connected between pin 1 & 2 on J5, the RBL will first check for valid boot image in NOR flash sector 0 and if it finds a valid image, the RBL will execute it. Otherwise, the RBL will load and execute SPI flash bootloader.

  The building instructions for boot loader can be found in "Building Bootloader" section.

Examples

Following examples and the CCS project files for those are included in the IA-SDK installation package. For details on importing and building samples applications in CCS, please see the AM335x Industrial SDK Getting Started Guide. The binaries generated using the below given projects will work on both ICE and IDK without any other modifications.

Supported Boards

Application/Board	IDK	ICEv1	ICEv2
EnetLWIP_Example	✔	✗	✓*
EtherNet/IP(ICSS)	✓	✓	✓**
EtherNet/IP(CPSW)	✓	✗	✓**
EtherCAT	✓	✓	✓**
UartEcho	✓	✓	✓
i2c_led	✓	✓	✓
Profibus	✓	✓	✓
PROFINET RT	✓	✓	✓**

*Works over ETH0 only
**Proper jumper settings required (EtherCAT works in ICSS mode only)

Jumpers J18 and J19 need to be set accordingly to select CPSW or ICSS mode. Pin2 and Pin3 need to be connected for ICSS mode and Pin1 and Pin2 for CPSW mode.

EnetLWIP_sysbios

This example illustrates how the Ethernet driver and TCP/IP stack can be used in a SYS/BIOS application to demonstrate a sample web server. This application uses the starterware Ethernet driver and LWIP TCP/IP stack. The application assigns a static IP address (192.168.1.2) for the device and hosts a very simple web server on that IP. The application also prints status messages on UART console. To view the web server, connect the AM335x device to the PC with a Ethernet cable and go to http://192.168.1.2 using any web browser. In this example the LWIP stack has been built as a static library and later linked to application.

This application is dependent on lwip_static.lib, drivers.lib, am335x_platform.lib and sys_bios_driver.lib. The project files for these libraries are included in the SDK. They can be rebuild with any modification required to implement a specific desired functionality. Upon modifying and building the libraries, the user should re-build the application as well.

NOTE 1:   During startup of the application, an ethernet cable should be plugged in to ETH0

NOTE 2:   The end machine connected to the board should also be in the same subnet as the assigned IP address

EtherNet/IP

NOTE 1:  Permanent storage of Ethernet/IP device parameters are enabled and are stored in SPI Flash at various offsets as defined in file eip_main.h

NOTE 2: DLR node is not supported in Ethernet/IP over CPSW.

NOTE 3: To add ACD(Address Conflict Detection) support in the application, a legacy method is used for configuring NDK parameters. In this approach configuring of NDK is done using the Configuration APIs rather than the XGCONF configuration tool within CCS. This is because a configuration added through XGCONF tool will be overridden. Please refer the link for more information on this approach.

NOTE 4: For passing the Subnet Mask tests (Test 4.1) specified in ODVA Conformance test report, rebuilding of the NDK is required. Macro _INCLUDE_ACD_SUPPORT must be defined in the file NDK_INSTALL_DIR\packages\ti\ndk\stack\lli\lliin.c . Then the NDK is rebuilt

NOTE 5: The Ethernet/IP application can be modified to work as a Switch application by removing the Ethernet/IP dependencies. The steps to create Switch application can be found here

NOTE 6: The NDK performance of the ICSS Switch Driver can be improved by increasing Queue size (Prioriy Queue 4 in case of Ethernet/IP). To enable this improvement change the macro QUEUE_4_SIZE in icss_switch.h from 97(3KB) to 194(6KB). However it is important that the total Queue size is not more than 12KB.

The example is an EtherNet/IP adapter demo application based on Molex EtherNet/IP stack on top of NDK TCP/IP stack  . The EtherNet/IP is an industrial networking standard that takes advantage of commercial off-the-shelf Ethernet communication chips and physical media. The EtherNet/IP uses an open protocol (CIP) at the application layer. This example is a limited demo application that is constrained so that a user will be allowed to execute it for one hour only.
 

The Ethernet/IP on Industrial Communication SubSystem (ICSS) supports Beacon based DLR (Device Level Ring) node which is a ring redundancy protocol specified by ODVA, the main features of this implementation are

• Supports 200 us beacon interval and 400 us beacon timeout interval
• Supports learning table exception for Supervisor
• Dynamic start and stop. User can enable or disable DLR on the fly
• No user configuration required. The ring parameters get configured on their own.
   

The ACD(Address Conflict Detection) feature is enabled in the example. Upon startup, the application checks for the ACD enable bit stored in the SPI Flash (at offset 0xb3000). If disabled, the application starts immediately, otherwise it waits for the link to come up. Once the link is established, the ACD mechanism is started. The IP Address is obtained once the ARP probing is done and no duplicate IP Address is detected.

This application allows the user to carry out the following actions and can be configured via the serial console

1. Start mode – Start stack in IO exchange mode
2. Stop mode – Stop IO exchange mode
3. Run mode – In this mode IO Data will be exchanged with scanner
4. Idle mode - No Data exchange with scanner. Only communication.
5. Copy in-out mode – Copy the data from scanner to the OUT data.
6. Increment mode – Stack will increment the OUT data periodically
7. Change IP Address - IP address of the device can be configured manually.
8. Erase Non Volatile Memory - This option will erase the stored device configurations from the non volatile memory

The EtherNet/IP adapter application can be run over the hardware Gigabit switch module of AM335x or over the low latency cut-thru switch implementation on ICSS. The switch choice is selectable at compile time. The default build configuration is for the ICSS switch. The macro ‘ USE_CPSW_DRIVER’ can be globally enabled to build the application for hardware gigabit (CPSW) switch.   Please see AM335x NDK driver API Guide for details on the NDK based CPSW and ICSS switch driver. Please see AM335x ICSS Switch API Guide for details on ICSS Switch Implementation.

The stc file used for the ODVA CTT is provided along with the application in stc folder. The EDS file for the application is located at $(IA_SDK_HOME)\protocols\ethernetip_adapter\eds folder. Separate stc files eds files are provided for the CPSW and ICSS Implementation. The Ethernet/IP Driver API guide is available here - EthernetIP Driver API Guide

The Ethernet/IP Application uses a Module status LED (D4 on ICE V1 and D1 on ICE V2) and a network status LED (D5 on ICE V1 and D2 on ICE V2).

For a quick checkout and demonstration of the EtherNet/IP functionality, an EIPTool, available for free from Molex, can be used to establish CIP connections and query or set CIP attributes. Additional details on using EIPTool with an example application can be found here Using EIPTool with AM335x EtherNet/IP Adapter Application.

Running application on ICE V2
For operation with the ICE V2,  the Jumpers J18 and J19 must be set to select CPSW or ICSS mode. Pin2 and Pin3 are connected for ICSS mode and Pin1 and Pin2 are connected for CPSW mode. 

EtherCAT

NOTE 1: SDK Supports two different versions of EtherCAT application.

1 . Simple Demo Application  - An EtherCAT sample application built using  the pre-built EtherCAT stack library (ecat_slave_stack.lib). This allows limited development using the SSC5.10 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 application for EtherCAT. The project files for this application can be found in $(IA_SDK_HOME)\examples\ethercat_slave. 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 that provides full flexibility and configurability. However this application requires access to the 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 obtain the SSC 5.10 source code from the ETG website and apply the provided patch. The project files for this application can be found in $(IA_SDK_HOME)\protocols\ethercat_slave\ecat_appl. Please see the details in later sections. For more information, refer the section on "Building Full Feature EtherCAT Application" of this document

NOTE 2: By Default, Both EtherCAT applications embed the PRU firmware binaries into the application binary. However, loading PRU firmware from SPI flash is also supported in this version. In this case, the EtherCAT application will load PRU firmware from SPI flash memory (if available) during run-time. This saves almost 16KB memory by reducing the binary size. The EtherCAT binary expects the PRU0 firmware at an offset of 0x98000 from the beginning of SPI memory and PRU1 firmware at an offset of 0x9C000 from the beginning of SPI memory

NOTE 3: 1. Debug  - This configuration builds the application with maximum debugging support including Real Time Analysis(RTA) and Logging. The application is built to execute from DDR. This build supports online Application upgrade .

2. IRAM - This configuration builds the application in Thumb mode, optimized for space, with no RTA and logging support. This build will be executed completely from internal memory( without DDR). The EtherCAT application built in this mode expects PRU firmware to be flashed in SPI flash memory. Please note that the CCS build will generate a concatenated( ARM and PRU binaries) by default using batch file 'cat_appl_bins.bat'. This newly created binary can be flashed to SPI Flash at 0x20000 so that both ARM and PRU binaries will be flashed in a single shot. This build supports online Application upgrade.

3. NOR  - This configuration builds the application with no RTA and logging support. Built to be executed from NOR Flash and internal RAM (without DDR use).

4. Release - This configuration builds the application with no RTA and Logging support. This build is intended to be executed from DDR. This build supports online Application upgrade

NOTE 4:   Both EtherCAT applications support non-volatile storage of ESI EEPROM. The application writes the data into non-volatile SPI 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

NOTE 5:   In addition to the Default TI application (in earlier releases), the full-feature application in release 1.0.0.9 or newer can also be configured to run as a CiA402 slave. Refer to the section "Building Full Feature EtherCAT Application" for details

This folder has TI EtherCAT slave simple demo application along with configuration xml file. The user can start and build the CCS5.1 project named ethercat.upon successful build, files named "ethercat_SD.bin" and "ethercat_SPI.bin" will be generated (in sdk\examples\ethercat_slave\Debug). ethercat_SD.bin is for SD card and ethercat_SPI.bin is for SPI flash

On startup, the application will set digital out LEDs D30, D29, D27 and D25 in ICE V1, and D14, D10, D8 and D7 in ICE V2. This indicates that slave is up and in INIT state.

Note that this is different from start-up behavior in prior SDK releases(1.0.0.6 or older) where digital LED animation occurs in bit shift pattern.

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. More details can be found here.

1. Install TwinCAT3 (A one month evaluation is available for free download from the Beckoff website TwinCAT 3 Download. Select the eXtended Automation Engineering (XAE) mode of installation.
2. Copy sdk\examples\ethercat_slave\esi\TiEtherCATLib.xml to <Drive>:\TwinCAT\3.1\Config\Io\EtherCAT folder
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
6. Connect CAT5 Ethernet cable from TwinCAT PC to EtherCAT IN/Port0(J8) of IDK. If you have multiple IDKs in chain, please connect from EtherCAT OUT/Port1 (J9) to Port0 of next IDK. For the last IDK in chain, Port1 will be left open.
7. 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)
8. 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.
9. A dialog will pop asking Load I/O Devices, select Yes
10. Next dialog asks confirmation to Activate Free Run - select Yes. This will put TI ESC into OP mode.
11. The application should show digital out LEDs 1 to 8 to 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.
    
    
    
    
    TwinCAT Status / Control Display
    

1. 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.
   
   
   
   TwinCAT LED Control Display
   

Online application upgrade

        TI EtherCAT slave supports upgrading the application using FoE. A user can download and execute an upgraded version of the application from an EtherCAT master without disturbing the basic EtherCAT communication (without reset of PRU-ICSS running EtherCAT firmware). Note that this is a sample implementation ONLY for customers implementing SemiConductor Device Profile: Firmware upgrade over EtherCAT v0.1.11. Steps to be followed to do firmware upgrade from TwinCAT master is described here.

       

This application is dependent on drivers.lib, am335x_platform.lib, sys_bios_driver.lib and ecat_slave_stack.lib. The project files for these libraries except for ecat_slave_stack.lib are included in the SDK and they can be rebuild with any modification required. Upon modifying and building libraries, users should re-build the application as well.

For more information, Please see Configuring TwinCAT For AM335x

UartEcho

The UartEcho example illustrates how the UART Peripheral can be used from a SYS/BIOS application. This application requires that the serial port on the EVM is connected to the host serial port via a NULL modem cable. A serial terminal application (like teraterm/ hyperterminal/ minicom) is run on the host. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

The application prints a message on the UART console in specific intervals and echos the character sent to it.

This application is uses drivers.lib, am335x_platform.lib and sys_bios_driver.lib. The project files for these libraries are included in the SDK and can be rebuild with any modifications required. Upon modifying and building libraries, it is recommended to re-build the application as well.

i2c_led

The i2c_led application illustrates how IDK LEDs can be accessed using the i2c and GPIO modules from a SYS/BIOS application. This application accesses the 8 output LEDs, run LED, error LED, act0 LED and act1 LED. The output LED's are accessed through i2c module. The other LEDs are access through the GPIO module.

Once loaded successfully, all the above mentioned LEDs blinking in specific pattern.

This application use drivers.lib, am335x_platform.lib and sys_bios_driver.lib. The project files for these libraries are included in the SDK and can be rebuild with any modification required. Upon modifying and building libraries, it is recommended to re-build the application as well.

Profibus

NOTE: As per the SLA terms, TI cannot distribute the PROFIBUS slave stack from Technologie Management Gruppe (TMG) Code in source format. An evaluation library is provided with this release. For production use, please obtain the license and software directly from TMG.

This application uses drivers.lib, am335x_platform.lib, sys_bios_driver.lib, utils.lib, platform.lib, system.lib, and profibus.lib. The project files for these libraries except for profibus.lib are included in the SDK. They can be rebuild with any modifications required. Upon modifying and building libraries, it is recommeded to re-build the application as well.

Texas Instruments use PROCENTEC's ProfiTrace 2.6.1 to test the TI PROFIBUS DP slave sample app.. However, any PROFIBUS master can be used. Alink is the link to set up PROCENTEC's ProfiTrace 2.6.1 master is http://www.procentec.com/downloads/profitrace/ProfiTrace2-Manual-EN.pdf

A quick guide to set up TI Profibus slave with master is: http://processors.wiki.ti.com/index.php/PROFIBUS_DP_slave_demo_setup_on_AM335x

To set up the board the following steps are taken:

• On the master side:
  • Copy PRU_OCDA.gsd file provided in the SDK into master GSD library
  • Scan the GSD library in the master
  • Create/Add "AM335x Evaluation Module (EVM)" slave in the project/network
  • Add modules (for e.g. 8byte input, 8byte output which is default) for the slave and activate
  • Initialize master, set baud rate, and operate

• On the slave side:
  • For ICE V1 : Set Jumper on J7 (pin 1 and 2), J6, and J5 as shown and remove Jumper J4
  • For ICE V2 : Set Jumpers between pins 2 & 3 on J18 and J19 to slect ICSS mode
                       Set jumper on J7, J8 ( pin 1 and 2) and J10. Remove Jumper on J6
  • After powering on the board the bootloader will load the APP from SDMMC/SPI flash/NOR flash into DDR/Internal RAM/Cache
  • The boot logs can be seen on serial console
  • The APP waits for 5 sec to obtain the station address from serial console, if nothing is set then assume that the default station address 5. For changing the station address connect serial console as shown in the above snap shots. Hit Enter key to change station address, then enter the valid station address and hit enter again to start the APP. For ICE board after powering on and connecting the serial console, press the reset button to set the station address.
  • APP will print the menu on the serial console.
    • The input can be changed by pressing 'i' on keyboard
    • The master output updates are seen on serial console and output byte 3 toggles the LEDs on top of J17 (in IDK) or below J9 (in ICE) in a pattern sent by the master on byte3 (enable watchdog/modify I/O)
    • 'd' gives the DP status - 0x80 or 0x81 indicates the data exchanges, 0x0 indicates that data exchange is stopped

PROFINET RT/MRP v2.3

NOTE 1: PROFINET I/O Device is certified by COMDEC for Conformance Classes A and B

NOTE 2: As per the SLA terms, TI cannot distribute the PROFINET slave stack code from Molex in source format. The evaluation library is provided with this release. For production use, one has to obtain the license directly from Molex

NOTE 3: As per the SLA terms, TI cannot distribute the SNMP stack code from Interniche in source format. The evaluation library is provided with this release. For production use, one has to obtain the license directly from Interniche. Please refer section Building full feature SNMP stack to rebuild the SNMP stack

This example is a PROFINET I/O Device(slave) application based on Molex PROFINET stack. PROFINET is a real-time Ethernet standard for high-speed, deterministic communications used in a wide range of industrial applications including factory automation, process automation and building automation.

This example also incorporates SNMP(Simple Network Management Protocol) using Interniche SNMP stack. SNMP is required for managing devices in the network. This application supports SNMP MIB-2(System and Interfaces), LLDP-MIB, LLDP-EXT3-MIB and LLDP-PNO-MIB which are mandated for Conformance Class B. Current implementation of the LLDP-MIBs are limited in nature as the integration between PROFINET stack and SNMP interface is incomplete. The SNMP stack available in the example is a limited version, and shuts down after 1024 SNMP requests.

During start-up, the I/O Device is assigned an IP Address of 0.0.0.0 . The PROFINET master will have to configure the desired IP Address and device name to the I/O device before an I/O connection can be established with the device. Once the application is up, PROFINET I/O device will start communicating with a PROFINET PLC, or a PROFINET IO Tester.

The GSD file used for configuring the I/O Device in the master side is provided along with the application in GSD folder.

PROFINET I/O Device has an integrated two-port cut-through learning switch. Switch handles the non real-time traffic and it has been interfaced with the PROFINET stack and TCP/IP (NDK) stack.It implements the PROFINET Quality of Service (QoS) using four priority queues on host and port interfaces. It implements PROFINET Filter Database for multicast addresses.Please see AM335x NDK driver API Guide for details on NDK based ICSS switch driver.

On ICE V1,one tri-colour LED will blink in blue and on ICE V2, the LED will blink in orange when the application is running.

A simple sample I/O Application has been provided to demonstrate the usage of PROFINET implementation. All the 1440 bytes of output data are exposed to the application. Sample I/O application simply uses the first byte of output data and maps it to the Digital Output LED's on the board. It also implements a mechanism to read the Digital Inputs. Interpretation of Digital Inputs by sample application is described below:

• Setting Jumper on Digital Input 0 generates an Alarm. This is an external way to manually generate the alarms from the I/O device.
• Setting Jumper on Digital Input 1 generates a bit shift pattern input. Application reads this input and transmits to PLC.
• Setting Jumper on Digital Input 2 generates a fixed test data input.

User can write a simple PLC program where input data of I/O device is transmitted back by PLC as output data. For example, a Jumper can be inserted in Digital Input 1 on I/O device to generate a bit shift pattern which is then transmitted back by PLC to demonstrate the moving LED light on the Digital Output LED's.

Details on setting up a PROFINET Connection with a PLC is included in sdk/protocols/profinet_slave/docs

NOTE :The following API Guide is applicable only till ISDK 1.1.0.6. For higher versions, please find the docs in sdk/protocols/profinet_slave/Docs/AM335X_Profinet_Slave_RT_API_Guide.chm

The PROFINET Driver API guide is available here - PROFINET Driver API Guide

Running application on ICE V2
Jumpers J18 and J19 need to be set properly to select ICSS mode. Pin2 and Pin3 need to be connected for ICSS mode 

Building Libraries/Binaries for IDK and ICE

Libraries/Binaries for IDK and ICE need not to be built separately. The run-time board detection mechanism will identify the board and execute accordingly.

Building Full Feature EtherCAT Application

The ethercat example application found in $(IA_SDK_HOME)\Examples\ethercat folder is a limited development application. To have a full development capability on AM335x, users needs to get the EtherCAT source code from Beckhoff and use that with SDK. SDK provides all board specific implementation sources for EtherCAT and a patch file to modify Beckhoff source files for AM335x. This application can be found in $(IA_SDK_HOME)\protocols\ethercat\ecat_appl. This folder also includes the configuration xml file to be used for testing and it can be found in $(IA_SDK_HOME)\protocols\ethercat\ecat_appl\esi folder.

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

1. Download EtherCAT stack version 5.10 from ETG website and extract it to a local folder.
   
2. Apply ( See Apply instructions below) TI_ECAT.patch file found at $(IA_SDK_HOME)\protocols\ethercat_slave\ecat_appl\patch on extracted Beckhoff stack code.
   
3. Copy those patched Beckhoff source files (.c and .h) to $(IA_SDK_HOME)\Protocols\ethercat_slave\ecat_appl\EcatStack
   
4. Launch CCS and import ecat_appl project found at $(IA_SDK_HOME)\Protocols\ethercat_slave\ecat_appl to CCS
   
5. Define macros in ecat_appl\EcatStack\ecat_def.h as required for your application. (a) Ensure that TIESC_HW is set to 1. (b) 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.
6. Build the project. This will generate the application binary which can be used to run on AM335x.
   

Applying a Patch file

• Download Windows Patch Utility from gnuwin32 sourceforge. ( Note that this is not a TI tool - See licensing information page for more details)
• Extract the zip file to the Windows PC. Patch file utility(Patch.exe) can be found in bin folder.
• Launch DOS Command prompt ( Start->Run->cmd).
• CD to 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 C:\TI\am335x_sysbios_ind_sdk_1.0.0.7\sdk\protocols\ethercat_slave\ecat_appl\patch\TI_ECAT.patch -d c:\SSC_V5i0\SlaveFiles\src

Generating AM335x EtherCAT sources using Beckhoff SSC Tool

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 AM335x. But, by default, the generated files will not have TI specific changes to the stack code. However, there is a method to generate EtherCAT stack code with TI specific changes using SSC and it is described below. Please note that this procedure is applicable only for SSC version 5.1.0 with SSC Tool version 1.3.1

Below given are the steps to be followed.

1. Download EtherCAT stack version 5.10 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.3.0.
3. Launch SSC tool by double clicking SlaveConfigFile.escfg file found at SlaveFiles\cfg folder.
4. Select "Custom" and "TI AM335x Sample <Texas Instruments Incorporated>" on the shown dialog box.
5. Locate TI EtherCAT files on PC as required by SSC Tool. These files can be found either in  $(IA_SDK_HOME)\protocols\ethercat_slave\include or  $(IA_SDK_HOME)\protocols\ethercat_slave\ecat_appl\EcatStack. Ignore any warning shown during the process.
6. Update the SSC configuration.  

            * Go to Tools->Options and select “Configuration” tab

            * Click on “+’ sign

            * Select the TI_AM335x_1i1i0i4.xml file found at $(IA_SDK_HOME)\protocols\ethercat_slave\ecat_appl\patch and click OK.

1. Set DC_SUPPORTED to 1 if not set.
2. Save the project
3. Click "Project->Create new Slave Files" - This generate the ETherCAT Source files for TI AM335x device.
   
4. The generated files can be found at the SSC tool project file location. Please note that ecat_def.h generated by SSC tool will not have changes by TI and hence user will have to replace the generated ecat_def.h with the patched ecat_def.h

NOTE 1 : Please make sure the SDK path is updated correctly in TI_AM335x_1i1i0i4.xml

NOTE 2 : At Step 4, you can also import TI_AM335x_1i1i0i4.xml and skip Step 6

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 the application needs to work with some other ESI xml file, user need to generate corresponding ESI header file ( tiesc_eeprom.h ) and should re-build ecat_appl 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  $(IA_SDK_HOME)\tools\bin2header
  

                 Usage is as follows.

                           '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"

• Replace the existing file with new header file ( tiesc_eeprom.h) to $(IA_SDK_HOME)\Protocols\ethercat_slave\ecat_appl\src
  
• Rebuild the application.
  

Building Full Feature SNMP stack

SNMP is provided as a library in the Industrial SDK with a limit of 1000 SNMP requests(after which it will shutdown). To have full development capability, users have to get the stack from Interniche(please contact - http://www.iniche.com/snmp.php )

The SNMP stack project files can be found in $(IA_SDK_HOME)\protocols\snmp\snmp_core. Once the user has access to the stack source, they can copy the files into this folder and re-build the library to get full development access.

The steps for building full feature SNMP stack using Interniche SNMP source are given below.

1. Copy the SNMP stack source to $(IA_SDK_HOME)\Protocols\snmp\snmp_core\source
   
2. Launch CCS and import snmp_core project found at $(IA_SDK_HOME)\Protocols\snmp\snmp_core to CCS
   
3. Build the project. This will generate the application binary(at $(IA_SDK_HOME)\Protocols\snmp\stack_lib) which can be used to run on AM335x.
   

Building Bootloader 

Boot loader project coming with sdk includes three build configurations and they are described below.

1. Debug -  This configuration builds the application with no optimization in place , in 32 bit mode and with maximum debugging support. The size of the boot loader binary would be large. Builds the binary to be executed from SD card or SPI flash depending on the post-built steps defined.
   
2. Release - This configuration builds the application in 16 bit mode and optimized for space. Builds the binary to be executed from SD card or SPI flash depending on the post-built steps defined.
   
3. NOR -  This configuration builds the bootloader for ICE V1 to be executed from NOR Flash.
   
4. NOR ICE V2- This configuration builds the bootloader for ICE V2 to be executed from NOR Flash.
5. FastBoot_Spi -This configuration builds the SPI bootloader for ICE V2 in fast Boot mode.The binary generated needs to be executed from SPI Flash

Once the build configuration is selected,  follow the given steps to build the boot loader.

• Import Bootloader project found at $(IA_SDK_HOME)\starterware\build\armv7a\cgt_ccs\am335x\evmAM335x\bootloader directory to CCS. See importing and building instructions section for details.
• Import dependent starterware projects. They are drivers, platform and mmcsdlib. They can be located at  $(IA_SDK_HOME)\starterware\build\armv7a\cgt_ccs\am335x\evmAM335x\.
• Set build configuration for dependant projects as "FixedPoint". Libraries generated with other configurations won't link with bootloader application because of "Floating Point support" mismatch.
• Build dependent projects in  CCS.
• Set predefined macros as follows   
  • For IDK, include HW_IDK  and remove SPI macro.
  • For ICE V1 , include HW_ICE and SPI.
  • For ICE V2 , include HW_ICE, HW_ICE_V2 and SPI.
• Set the post build script arguments properly. See Post Build Script section fro details.
• Build bootloader project.
  
• Successful build will generate boot.out and binary file in $(IA_SDK_HOME)\starterware\binary\armv7a\cgt_ccs\am335x\evmAM335x\bootloader 
  

Generating Executable Binary - Post Build Script

Post build script file(post_build.bat) can be found at $(IA_SDK_HOME)\Tools\post_build . 

This Script generates a plain executable binary(.bin) file from .out file and adds a header to it depending upon the type of binary and binary storage location.

Parameter List for post_build.bat

• Param 1 - CCS Install path
• Param 2 - Code Gen tool Install path
• Param 3 - .out file path
• Param 4 - .out file name
• Param 5 - isdk_image.exe path
• Param 6 [Optional] - Binary type [0- bootloader,1-Application]
• Param 7 [Optional] - Binary Storage type [ 0- SPI & SD , 1-MMCSD Card, 2- NOR Flash,3- SPI Flash]
• Param 8 [Optional] - Load address for the binary in hexadecimal format. If not provided, default values will be set. This has no effect in case NOR Flash.
  
• Param 9 [Optional] - Run  address for the binary in hexadecimal format. If not provided, default values will be set
  

There are two binary types - Bootloader binary and Application binary.
There are three storage locations - SPI Flash, MMC/SD card or NOR Flash.

Examples :-

1. Generate a bootloader binary to be stored in SPI Flash

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "3"
2. Generate a bootloader binary to be stored in SD Card

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "1"

2. Generate a bootloader binary to be stored in NOR Flash

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "boot" "TI_IMAGE_PATH" "0" "2" "0x08000000" "0x08000000"
3. Generate a application binary to be stored in SD card and SPI Flash and executed from DDR

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "0" "0x80000000" "0x80000000"

 4. Generate a application binary to be stored in MMCSD Card and executed from internal RAM

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "1" "0x402f8000" "0x40300000"

5. Generate a application binary to be stored in NOR Flash and executed from NOR

     post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "2" "0x08010000" "0x08010000"

6. Generate a application binary to be stored in SPI Flash and executed from DDR

     post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "3" "0x80000000" "0x80000000"

Concatenating ARM and PRU binaries

SDK provides a utility(isdk_merge.exe) to concatenate ARM side binary file and PRU binaries into a single file.This can be found at $(IA_SDK_HOME)\Tools\isdk_merge.

This is useful when both ARM and PRU binaries are stored in SPI flash.   For example, EtherCAT application built in IRAM build configuration expects both ARM side binary and PRU firmwares at SPI Flash memory. By concatenating these files, multiple flashing operation is being eliminated.

Usage

   isdk_merge <output_file> <1st_input_file> <offset_from_beg_of_first_file> <2nd_input_file> <offset_from_beg_of_sec_file> <3rd_input_file>

Description

   output_file -  The full name of concatenated file to be generated

   1st_input_file - The full name of first file to be concatenated

   offset_from_beg_of_first_file - The offset at which the second file need to be placed with respect to the begening of first file

   2nd_input_file - The full name of second file to be concatenated

   offset_from_beg_of_sec_file - The offset at which the third file need to be placed with respect to the begening of second file

   3rd_input_file - The full name of third file to be concatenated

Example

   isdk_merge C:\TI\ecat_appl_pru.bin C:\TI\ethercat_SPI.bin 0x78000 C:\TI\ecat_frame_handler_flash.bin 0x4000 C:\TI\ecat_host_interface_flash.bin

Technical Support and Product Updates

For further information or to report any problems, contact http://community.ti.com or http://support.ti.com.