AM437x SYSBIOS Industrial SDK 02.00.00.01 User Guide

AM437x SYSBIOS Industrial SDK 02.00.00.01 User Guide

Revision History

Revision	Date	Description
1.0	13-Jun-2014	Created initial version of the document
1.1	16-Oct-2014	Updates for official release

AM437x Industrial SDK Introduction

The SYSBIOS-based software development kit (SDK) for industrial communications is designed for the Sitara AM437x ARM Cortex-A9 microprocessor family to enable customers add real-time industrial communications, motor control and feedback capabilities 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 motor feedback capabilies like EnDAT, BISS, Sigma Delta Decimation Filter, 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 AM437x combines all the software components and tools needed to begin development of SYS/BIOS-based applications on the ARM. The SDK supports AM437x IDK hardware platform and includes the following

• Open source SYS/BIOS Real Time Operating System (RTOS)
• Bootloader for AM437x IDK with support to boot from various peripherals
• Library of peripheral drivers integrated with SYSBIOS supporting IDK
• Sample applications demonstrating peripheral use cases for IDK
• Code Composer Studio integrated development environment (IDE) v.6
• Sample industrial input/output applications over communication protocols such as EtherCAT
• Motor and Drive feedback capability with support for interfaces like EnDAT, Sigma Delta Decimation Filter etc
• Evaluation versions of protocol stacks for industrial communications such as EtherCAT, EnDat and many others to facilitate software development

Industrial SDK is supported on IDK

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

Reference Documents

• SYS/BIOS Getting Started Guide
• SYS/BIOS User Guide
• AM437x SYSBIOS Industrial SDK Getting Started Guide
• AM437x SYSBIOS Industrial SDK 02.00.00.01 Release Notes

SDK Directory Structure

|--- sdk

|   |--- control

|       |---foc

|       |---math_blocks
 
|   |--- docs

|       |---SYSBIOS Industrial SDK 02.XX.XX.XX User Guide.pdf

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

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

|   |--- examples

|       |--- endat_diagnostic

|       |--- ethercat_slave

|           | --- esi

|       |--- led_toggle

|       |--- motor_control

|       |--- uart_echo

|   |--- interfaces

|       |--- endat_master

|               |--- driver

|               |--- firmware

|               |--- include

|       |--- pru_onchip_adc_sampling

|               |--- firmware

|   |--- os_drivers

|       |--- include

|       |--- lib

|       |--- source

|   |--- protocols

|       |--- ethercat_slave

|           |--- docs

|           |--- ecat_appl

|               |--- esi

|               |--- patch

|               |--- EcatStack

|           |--- firmware

|           |--- include

|           |--- stack_lib

|   |--- starterware

|   |--- tools

|       |--- bin2header

|       |--- gel

control - This folder contains source code required for Motor control(FOC and IQMATH)

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

interfaces - This folder contains supported motor control interface source, header and firmware

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

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.

System Requirements

Hardware

• AM437x IDK
• Windows Host Machine with minimum 2GB RAM
• Micro SD Card for IDK
  

Software 

• Code Composer Studio version CCS 6.0.0.00190
  
• SYS/BIOS 6.40.3.39 Real Time Operating System
  
• XDC Tool 3.30.4.52_core
• Compiler GNU v4.7.4 (Linaro)
• 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.

• 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.

Pre-Built Binaries and Libraries

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

• libecat_slave_stack_am437x.a   -   EtherCAT Slave Stack library including PRU Firmwares

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

• libsys_bios_driver.a  -  SYS/BIOS specific implementation for accessing peripheral devices and EVM functionality

                                        SDK Path - $(IA_SDK_HOME)\os_drivers\lib

• Starterware Libraries Device Abstraction Layer libraries

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

• endat_diagnostic - Sample application demonstrating EnDat master functionality.
  
• ethercat - Sample application demonstrating EtherCAT slave functionality.
  
• led_toggle - Sample application demonstrating LED toggling on the board.
• motor_control - Sample application demonstrating motor control.
  
• uartecho - Sample application demonstrating UART communication.

SYS/BIOS Driver

AM437x 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,McSPI module access.  Other modules will be added to this library in future releases. 

Bootloader

Starterware AM437X provides a simple bootloader, which can be copied to an MMCSD card or flashed to QSPIflash, which after a power-on-reset can bootstrap the board. Additionally, QSPI/SD card bootloader can load an application from the MMCSD card/QSPIFlash to DDR or Internal RAM and transfer the control to the application. This can be used for out-of-box experience.

Refer Starterware User Guide in {IA_SDK_HOME}\starterware\docs for more details on loading and building the Bootloader

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 [SYSBIOS Industrial SDK Getting Started Guide]. 

EnDat diagnostic

EnDat master diagnostic application for SYS/BIOS. This application needs that the USB port on the EVM be connected to the host, UART over USB is presented to the host by doing so. A serial terminal application (like teraterm/hyperterminal/minicom) has to be run on the host, select the serial port corresponding to the one emulated over USB by the EVM. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

EnDat driver provides a defined set of API's to expose EnDat master interface. Diagnostic invokes API's to initialize platform, get a cookie for EnDat, configures to host trigger mode, selects the channel and then firmware would be run. Next it wait's till EnDat is initialized. It then finds out encoder details like serial number, position resolution etc, these are displayed to the user.

Once initial setup is over, diagnostic provides user with a self explanatory menu. Two types of menu options are present, one type (1-14) to send EnDat command as per EnDat 2.2 specification. Other type (100-105) allows to configure timings, simulate motor control loop, continuous mode control and monitor raw data.

Upon user selecting an EnDat command, diagnostic asks for more details to frame the command, a basic sanity check on the user entered values is executed. Then it invokes EnDat API to process the command, this returns once EnDat command is completed. Now received data is processed, validated using the defined API's and finally user is presented the result of the command.

EtherCAT

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

1 . Simple Demo Application  - An EtherCAT sample application built using  pre-built EtherCAT stack library (libecat_slave_stack_am437x.a). This allows limited development using 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 OOB 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 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. Hence, to build this application, user need to get the SSC 5.10 source code from 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. This application includes motor control functionality

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

This folder has TI EtherCAT slave simple demo application along with configuration xml file. User can start and build the CCS6 project named ethercat.upon successful build, file named "ethercat_ti.bin" will be generated (in sdk\examples\ethercat_slave\Debug__GNU) which can be used flashed to QSPI or copied to SD card

On startup, application will set digital out LEDs 2,4,6 and 7 . 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. More details can be found here.

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_slave\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 EtherCAT IN/Port0(J6) of IDK. If you have multiple IDKs in chain, please connect from EtherCAT 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
13. To control the Motor(Available in full application ONLY), use TI Boxn(ti-esc)>Motor Outputs->Data to set the speed[-200 to 200, clockwise and anti-clockwise] and  TI Boxn(ti-esc)>Motor Outputs->Command to start/stop the motor(writing 1 to command starts the motor)

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

LED Toggle

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 and two Tricolor LED's. Output LED's are accessed through i2c module 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.

Motor Control

Standalone motor control application for SYS/BIOS. This application needs that the USB port on the EVM be connected to the host, UART over USB is presented to the host by doing so. A serial terminal application (like teraterm/hyperterminal/minicom) has to be run on the host, select the serial port corresponding to the one emulated over USB by the EVM. The host serial port is configured at 115200 baud, no parity, 1 stop bit and no flow control.

Motor control application has been validated using Permanent Magnet Motor (BLY171D-24V-4000, Anaheim Automation) coupled to an EnDat 2.2 encoder (ROQ 437, Heidenhain). Motor can be controlled via console. Press enter in the console, user will be asked to enter motor control variables, simply pressing enter can bypass setting any variable - this would be helpful, especially if only one variable needs to be changed. Meaning of these variables change slightly with different build levels, default is LEVEL4 (closed speed loop with EnDat position feedback). Build level can be changed using BUILDLEVEL in foc.h, this would require rebuilding the project for it to make effect.

In LEVEL4, valid variables are lsw and speed. Default value of lsw is 0, make it 1 for open speed loop, 2 for closed speed loop. Speed has to be entered in rpm, it has been normalized for the motor mentioned above (i.e. 4000rpm). To reverse rotation, enter negative values.

In LEVEL5, valid variables are lsw and angle. lsw 0 (default) is position control off, make it 1 or 2 to turn on position control, enter desired angle in the range 0-360 for controlling the position.

LEVEL6, this is a combination of LEVEL4 & LEVEL5, valid variables are msw, lsw, speed and angle. msw 0 (default) means speed control mode, in this mode, use lsw & speed as mentioned in LEVEL4, angle doesn't make an effect with msw 0. Make msw 1 for position control, in this mode, use angle to change position as mentioned for LEVEL5, speed and lsw doesn't have an effect here.

FOC

NOTE 1: Before proceeding with closed speed loop or position control ensure that encoder is connected and coupled to the motor and position offset compensation updated as mentioned below

NOTE 2:When the motor is running, do not halt processor or connect/disconnect JTAG, bring motor to standstill first

NOTE 3:In LEVEL6, before switching from position control to speed control and viceversa, ensure that speed/position is set to zero (eg. before switching from speed control to position control mode, make speed as 0) and that motor is standstill

NOTE 4:Use power supply provided with AM437x IDK

Field Oriented Control (FOC) algorithm is used to control the motor. This is based on C2000 PMSM sensored servo FOC, which is very much tied to EQEP position feedback technique. FOC code has been adapted to use EnDat instead of EQEP for position feedback.

FOC implementation used here has 6 LEVEL's. LEVEL4 and LEVEL5 are the ones that would normally be used in practical applications, LEVEL3 and LEVEL6 for demonstration purposes, LEVEL1, 2 and 3 are used during initial setup.

Brief on relevant LEVEL's (all below are with closed current loop),
LEVEL3 - open speed loop
LEVEL4 - open speed loop, closed speed loop with EnDat feedback
LEVEL5 - position control with EnDat feedback
LEVEL6 - combination of LEVEL4 & LEVEL5 selection between it can be done at runtime

Position Offset Compensation

For a given setup, offset compensation for the encoder has to be found out, this need be done only once for a coupled motor encoder set. If the setup is decoupled, value has to be determined again. At runtime, position offset compensation value would be calculated by running the motor in LEVEL4 (default), the value can be observed @0x54442030 (float type) as soon as the motor is run (within a second) in closed speed loop (lsw = 2). Please note that runtime position offset capability is available in LEVEL4, though this works, is not fully reliable. If motor runs satisfactorily with runtime calculated position offset compensation value, use it, otherwise manually change position offset compensation and find the value at which q-axis (@0x54442204) and d-axis (@0x54442104) current drawn is minimum. Once position offset compensation value is obtained, either using the value automatically calculated at runtime or using the value found out manually, replace the following in foc.c,

#if (BUILDLEVEL < LEVEL5)
_iq OffsetE = _IQ(0.0);
#else
_iq OffsetE = _IQ(-0.67);
#endif
Uint32 ElecThetaCalibrateFlag;

to,

#if (BUILDLEVEL < LEVEL4)
_iq OffsetE = _IQ(0.0);
#else
_iq OffsetE = _IQ(<new position offset compensation value>);
#endif
Uint32 ElecThetaCalibrateFlag = 1;

The above updates position offset compensation value to be used for LEVEL4, LEVEL5 & LEVEL6.

NOTE :If runtime position offset compensation calculation is working reliably in the setup and if the requirement is only closed speed loop control, then code change (as mentioned above) is not required

PI tuning

PI controller is used. For a given setup, it may be required to tune current, speed and position PI controller parameters, to make it easy, these variables are exposed through PRU shared memory, which is modifiable at runtime through CCS. To achieve it, connect using Non Debuggable Devices -> CS_DAP_DebugSS, add relevant variables to it (don't forget to typecast it to float).

PI structure base address as follows (refer control/math_blocks/pi.h for more details),

d-axis current (id) - 0x54442100
q-axis current (iq) - 0x54442200
speed (spd) - 0x54442300
position (pos) - 0x54442400

values that would have to be changed are,

Proportional gain (Kp) - 0xC
Integral gain (Ki) - 0x10
Maximum limit (Umax) - 0x14
Minimum limit (Umax) - 0x18

Eg., if you want to change Kp for speed PI, modify 0x5444230c (0x54442300 + 0xC)

Uart Echo

UartEcho example illustrates how UART Peripheral can be used from a SYS/BIOS application. A Micro USB cable should be connected between the IDK(J18) and the host machine. 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 'echoes' anything you type into the terminal.

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 AM437x, 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 AM437x. 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 AM437x.
   

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\sysbios_ind_sdk_2.0.0.1\sdk\protocols\ethercat_slave\ecat_appl\patch\TI_ECAT.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 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\EcatStack
  
• Rebuild the application.
  

Generating Executable Binary - Post Build Script

OBJCOPY is used to generate a binary(.bin) from a .out file. Then ti_image adds the ti_headers into the generated binary file(resulting in an _ti.bin)

Parameter List for Post build steps

• Param 1 - OBJCOPY path
• Param 2 - Output file format(Binary)
• Param 3 - Input Image path name
• Param 4 - Output Image path name
• Param 5 - ti_image.exe path
• Param 6 - Load/Run address for the binary in hexadecimal format.
• Param 8- Boot mode. For bootloader, value of <boot mode> should be corresponding bootmedia name i,e NAND/SPI/MMCSD/UART. For application, value of <boot mode> should be NONE.
• Param 9- Input Image path name
• Param 10- Output Image path name

Example :-

Generate a bootloader binary to be stored in qSPI Flash or MMCSD

"${CG_TOOL_ROOT}/bin/arm-none-eabi-objcopy" -O binary "${workspace_loc:/${ProjName}}/Debug/ecat_appl.out" "${workspace_loc:/${ProjName}}/Debug/ecat_appl.bin" & "${IA_SDK_HOME}/starterware/tools/ti_image/tiimage.exe" "0x80000000" "NONE" "${workspace_loc:/${ProjName}}/Debug/ecat_appl.bin" "${workspace_loc:/${ProjName}}/Debug/ecat_appl_ti.bin"

Technical Support and Product Updates

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