AM335x SYSBIOS Industrial SDK 01.00.00.02 User Guide

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

AM335x SYSBIOS Industrial SDK 01.00.00.02 User Guide

Revision History

Revision	Date	Description
1.0	14-Feb-2012	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, 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.5
• Sample industrial input/output applications over communication protocols such as EtherCAT, PROFIBUS and other Ethernet and serial based Fieldbus Industrial Ethernet protocols
• Evaluation versions of protocol stacks for industrial communications such as EtherCAT, PROFIBUS and many others to facilitate software development

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

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

Reference Documents

• SYS/BIOS Getting Started Guide
• SYS/BIOS User Guide
• StarterWare Getting Started Guide
• StarerWare User 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 

|   |--- drivers 

|       |--- include 

|       |--- lib 

|       |--- src 

|   |--- examples 

|       |--- ethercat 

|           | --- esi

|       |--- i2c_led 

|       |--- uart_echo 

|    |--- platform 

|       |--- am335x 

|           |--- evmam335x 

|               |--- include 

|               |--- lib 

|               |--- src 

|   |--- protocols 

|       |--- ethercat 

|           |--- docs 

|           |--- ecat_appl

|               |--- esi

|               |--- patch 

|               |--- src

|           |--- firmware 

|           |--- include 

|           |--- stack 

|   |--- starterware 

|   |--- tools 

|       |--- gel 

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

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

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

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
• Windows Host Machine with minimum 2GB RAM
• SD Card for IDK / Micro SD Card for ICE
• XDS 560/510 Class Emulators for debugging for IDK

Software 

• Code Composer Studio version CCS 5.1.0.06000 or later
• Serial console terminal application (like Teraterm, minicom, HyperTerminal)

SDK Setup

SDK setup will install following items in the machine. Please see the installation instruction here. (TODO Link)

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

Pre-Built Binaries and Libraries

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

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

                                        SDK Path - $(SDK_INSTALL_FOLDER)\platform\am335x\evmam335x\lib

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

                                        SDK Path - $(SDK_INSTALL_FOLDER)\protocols\ethercat\stack

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

                                        SDK Path - $(SDK_INSTALL_FOLDER)\drivers\lib

• drivers.lib                  -  StarterWare library for peripheral devices 

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\drivers

• platform.lib               -  Starterware EVM specific initialization library

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\evmAM335x\platform

• mmcsd.lib                 -  Starterware MMC SD Card library

                                        SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\mmcsdlib

• utils.lib                      -  StarterWare Utils library

                                         SDK Path - $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\utils

SDK does not have any pre-built binaries inluded, but binaires generated using SDK examples (given below) can be downlaoded seperately. Please see release notes for download link.

• EtherCAT                   - Sample application demonstrating EtherCAT functionality. This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK. 
• i2c_led                       - Sampel application demonstrating LED toggling on the board.This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK.
  
• uartecho                    - Sample application demonstrating UART communication.This is built for ICE board. For use on IDK, user will have to re-build the application with board-type set as IDK.
  

SYS/BIOS Driver

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 and UART module access. Other modules will be added to this library in future releases. This library supports both ICE and IDK.

Bootloader

Starterware AM335X provides a simple bootloader, which can be copied to an MMCSD card or flashed to SPIP flash depending up on board , which after a power-on-reset can bootstrap the board. Additionally it can load an application from the MMCSD card/SPI Flash to DDR and transfer the control to the application. This can be used for out-of-box experience. 

Bootloader for IDK

Upon board power on, the RBL [Read Only Memory BootLoader], residing in the ROM of the AM335X kickstarts. 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. RBL requires boot loader to be named as "mlo". RBL copies the boot loader to internal memory and gives control to it. Boot loader initializes PLL0 and PLL1 for all the 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 execute from DDR.

Bootloader for ICE

Upon board power on, the RBL, residing in the ROM of the AM335X kickstarts.RBL checks for the boot mode settings(SYSBOOT) and depending on the settings, loads boot laoder from SPI flash to internal memory and transfers control to it. The boot loader in turn looks for application(named as "app") in MicroSD card. If application is found in SD card, boot loader loads that into DDR and transfers control to it. Otherwise, boot loader loads the application from SPI flash to DDR and transfers control to it.

Building instruction for boot loader can be found in "Building Bootloader" section .

Examples

Following examples and the CCS project files for those are included in the sdk installation package. For details on importing and building samples applications in CCS, please refer "AM335x Industrial SDK Getting Started Guide" 

EtherCAT

 

NOTE

SDK Supports two different versions of EtherCAT application.

1 . Simple Demo Application  - An EtherCAT sample application built using  pre-built EtherCAT stack library (ecat_slave_stack.lib). This allows limited development using SSC5.0 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 OOB application for EtherCAT. The project files for this application can be found in $(SDK_INSTALL_FOLDER)\examples\ethercat. 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 (SSC 5.0.) in source format. Hence, to build this application, user need to get the SSC5.0 source code from ETG website and apply the the provided patch. The project files for this application can be found in $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl. Please see the details in later sections. For more information, refer the section on "Building Full Feature EtherCAT Application" of this document.

This folder has TI EtherCAT slave simple demo application along with configuration xml file. User can start and build the CCS5.1 project named ethercat and a file named "ethercat.bin" will be generated here sdk\examples\ethercat\Debug which needs to be loaded into SD card.

Application on booting will toggle digital out LEDs on top of J17 in a circular bit shift pattern. This indicates that slave is up and in INIT state.

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

1. Install TwinCAT (One month evaluation is available for free download from Beckhoff website [1]- select PLC mode of installation and check IO drivers box
2. Copy sdk\examples\ethercat\esi\TI_ESC.xml to <Drive>:\TwinCAT\Io\EtherCAT folder
3. Start TwinCAT system manager
4. Goto Options > Show Real Time Ethernet Compatible Devices and Install TwinCAT RT Ethernet intermediate driver. For best performance - it is recommended to use compatible NIC card listed Supported Network Controller by Beckhoff Ethernet Driver
5. Goto I/O - Configuration > I/O Devices - right click and select Append device and then select EtherCAT > EtherCAT. Device1 (EtherCAT) will be added to I/O devices
6. Connect CAT5 Ethernet cable from TwinCAT PC to ECAT IN/Port0(J8) of IDK. If you have multiple IDKs in chain, please connect from ECAT OUT/Port1 (J9) to Port0 of next IDK. For last IDK in chain, Port1 is left open.
7. Now right click Device1(EtherCAT)> select Scan Boxes...
8. TI Boxn(ti-esc) will be detected automatically
9. Now select Device1 (EtherCAT) and goto Actions > Select Set/Reset TwinCAT to Config Mode or use shortcut SHIFT-F4
10. A dialog will pop asking Load I/O Devices, select Yes
11. Next dialog asks confirmation to Activate Free Run - select Yes. This will put TI ESC into OP mode
12. Now user can control digital out LEDs using TwinCAT. Select TI Boxn(ti-esc)>DO Outputs > LED1-8 to control the output LEDs

This application is dependant on drivers.lib, evmam335x.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

UartEcho example illustrates how UART Peripheral can be used from a SYS/BIOS application. This application needs that the serial port on the EVM connected to the host serial port via a NULL modem cable. A serial terminal application (like teraterm/hyperterminal/minicom) is running 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 dependant on drivers.lib, evmam335x.lib and sys_bios_driver.lib. The project files for these libraries 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.

BY default, SDK comes with project that are set to generate binaries for ICE. To use this for IDK, re-build the application afte setting board-type to IDK. See Building Libraries/Binaries for IDK and ICE section for details.

i2c_led

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

Once loaded successfully, it can be seen that, all the above mentioned LEDs blinking in certain pattern.

This application is dependant on drivers.lib, evmam335x.lib and sys_bios_driver.lib. The project files for these libraries 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.

BY default, SDK comes with project that are set to generate binaries for ICE. To use this for IDK, re-build the application afte setting board-type to IDK. See Building Libraries/Binaries for IDK and ICE section for details.

Building Libraries/Binaries for IDK and ICE

Libraries/Binaries for IDK and ICE need to be built separately by providing correspoding pre-compiled macros. The steps to build a library or an application is as follows.

1. Import the Project to CCS. Please see Importing and Building Sample Project in CCS for details.
2. Right click on the imported project and select "Properties".
   
3. Call SetBoardType API from application main, immediatley after mmuInit() with argument AM335X_BOARD_TYPE_IDK or AM335X_BOARD_TYPE_ICE . This API sets the type of the board on which the application is expected to execute. This is applicable only for applications, not for libraries. 
   
4. Select Build->Built Steps and Provide required arguments for post-build steps. This is only applicable incase of application. For libraries, this step can be ignored.( Incase of application, the CCS generated .out file need to be converted to an executable binary, to be copied to SD card or flashed into SPI flash.SDK examples comes with a post build script file which will do the process. See "Generating Executable Binary" section for details on post build script.
5. Click and build the project. This will build library or application for the defined board.

Building Full Feature EtherCAT Application

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

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

1. Downlaod EtherCAT stack version 5.0 from ETG website and extract it to a local folder.
   
2. Apply ( See Apply instructions below) TI_ECAT.patch file found at $(SDK_INSTALL_FOLDER)\protocols\ethercat\ecat_appl\patch on extracted BeckHoff stack code.
   
3. Copy those patched BeckHoff source files (.c and .h) to $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl\src
   
4. Launch CCS and import ecat_appl project found at $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl to CCS
   
5. 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.1\sdk\protocols\ethercat\ecat_appl\patch -d c:\SSC_V5i0\SlaveFiles\src

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 curresponding ESI header file ( tiesc_eeprom.h ) and should re-build ecat_appl with the genarated .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  $(SDK_INSTALL_FOLDER)\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 $(SDK_INSTALL_FOLDER)\Protocols\ethercat\ecat_appl\src
  
• Rebuild the application.
  

Building Bootloader 

1. Import Bootloader project found at $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\build\armv7a\cgttms470_ccs\am335x\evmAM335x\bootloader directory to CCS. See importing and building instructions section for details.
2. Import dependant starterware projects. They are drivers, platform and mmcsdlib. They can be located at  $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\build\armv7a\cgttms470_ccs\am335x\evmAM335x\.
3. Set build configuration for dependant projects as "FixedPoint". Libraries generated with other configurations won't link with bootloader application because of "Floating Point suppport" mismatch.
4. Build dependant projects in  CCS.
5. Set the HW_IDK or HW_ICE macro depending upon the board.
6. Set the post build script arguments properly. See Post Build Script section fro details.
7. Build bootloader project.
   
8. Succesfull build will generate boot.out and binary file in $(SDK_INSTALL_FOLDER)\starterware\starterware-starterware-src\binary\armv7a\cgttms470_ccs\am335x\evmAM335x\bootloader 
   

Generating Executable Binary - Post Build Script

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

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

Parmeter 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 - ti_image.exe path
• Param 6 [Optional] - Binary type [0- bootloader,1-Application]
• Param 7 [Optional] - Binary Storage type [ 0-SPI Falsh, 1-MMCSD Card]
• Param 8 [Optional] - Binary file name to be generated

There are two binary types - Bootloader binary and Application binary.
There are two storage locations - SPI Flash and MMCSD card.

Application which will be copied to SD card does not require an header attached to it. So We dont need to provide 6th,7th and 8th parameters to the script in this case. The default .bin file can be renamed to "app" and used.

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" "0" "boot_SPI.bin"
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" "boot_SD.bin"
3. Generate a application binary to be stored in SPI Flash

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH" "1" "0" "appl_SPI.bin"

4. Generate a application binary to be stored in MMCSD Card -

      post_build.bat "CCS_INSTALL_ROOT" "CG_TOOL_ROOT" "PWD" "appl" "TI_IMAGE_PATH"

Technical Support and Product Updates

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