AM437x SYSBIOS Industrial SDK 02.00.00.02 User Guide

AM437x SYSBIOS Industrial SDK 02.00.00.02 User Guide

Revision History

Revision	Date	Description
1.0	03-Nov-2014	Created initial version of the document
1.1	19-Jan-2015	Expanded the description in various sections

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. The SDK enables 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. The SDK is optimized to support real-time industrial communications protocols such as EtherCAT, Profibus, Profinet, Ethernet/IP and motor feedback functions 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

The Industrial SDK is supported on AM437x IDK

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

Figure 1 AM437x Industrial Development Kit

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.02 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 the pdf versions of the 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 an 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

The 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

The installation process will use 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. This should be defined ether as a project or as a CCS user defined variable.

Pre-Built Binaries and Libraries

The 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

• libboard.a  -  StarterWare library for board details

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\board\lib\am43xx-evm\a9\ccs\am43xx_debug

• libdal.a  -  Starterware DAL specific initialization library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\dal\lib\am43xx-evm\a9\ccs\am43xx_debug

• libdevice.a  -  StarterWare library for peripheral devices

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\device\lib\am43xx-evm\a9\ccs\am43xx_debug

• libsoc.a  -  StarterWare SOC library

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\soc\lib\am43xx-evm\a9\ccs\am43xx_debug

• libutils.a  -  Starterware Utils libary

                                        SDK Path - $(IA_SDK_HOME)\starterware\binary\utils\lib\am43xx-evm\a9\ccs\am43xx_debug

The SDK does not include any pre-built binaries, however binaries generated using SDK examples (given below) can be downloaded separately. All of the pre-built binaries except the bootloader are board independent. Please see the release notes for download location 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

The AM437x SDK provides a driver library for accessing device peripheral modules from a SYS/BIOS application. This driver is basically an abstraction of the 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. Following a power-on-reset the MMCSD card or QSPIflash can bootstrap the board. Additionally, the 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 to provide an application load from reset. Refer to the 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 is a bidirectional interface for position encoders. During EnDat operation the EnDat master receives position information from the EnDat position encoder. The EnDat diagnostic application for SYS/BIOS demonstrates the EnDat master operation on the AM437x.
This application is controlled with a terminal interface using a serial over USB connection between the PC host and the EVM. Please connect a USB cable between the PC and the EVM. A serial terminal application (like teraterm/ hyperterminal/ minicom) is then run on the host. To configure, select the serial port corresponding to the port emulated over USB by the EVM. The host serial port should be configured to 115200 baud, no parity, 1 stop bit and no flow control.
The EnDat driver provides a defined set of API's to expose EnDat master interface. The diagnostic invokes these API's to initialize the platform, get a handle for EnDat, configure the host trigger mode, select the channel and run the firmware. Once these steps are executed, the driver waits for the EnDat to be initialized. It then reports the encoder details including serial number, position resolution etc, on the console.
Once initial setup is over, the diagnostic provides the user with a self explanatory menu. Two menu options are presented. One type (1-14) will send an EnDat command as per EnDat 2.2 specification. The other type (100-105) allows the user to configure timings, simulate motor control loop, perfom continuous mode control and monitor raw data.
After the user selects an EnDat command, the diagnostic asks for more details to frame the command and performs a basic sanity check on the user entered values. Then the EnDat API is envoked to process the command. The received EnDat is processed & validated using the defined API's. The result is then presented to the user.

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 configuration 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. Therefore, to build this application, user must 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. The user can start and build the CCS6 project named EtherCAT. Upon a successful build, a file named "EtherCAT_ti.bin" will be generated (in sdk\examples\EtherCAT_slave\Debug__GNU). This can be flashed to QSPI or copied to SD card. Please see the [Getting Started Guide] for details on building an application. Alternatively, "ethercat.out" can be load/run from CCS to A9.
This application demonstrates the EtherCAT interface, LED light controls. If the Full Featured EtherCAT Application is available, the application will also demonstrate a motor control application.

The Motor Control application demonstrates a sensored 3 phase sensored Field Oriented Control (FOC) for a single Permanent Magnet Synchronous motor (PMSM) using the onboard AM437x ADCs and optionally the EnDat 2.2 master interface with a EnDat encoder attached to the motor. The Motor control application has been validated using a Permanent Magnet Motor (BLY171D-24V-4000, Anaheim Automation). This is coupled to an EnDat 2.2 encoder (ROQ 437, Heidenhain). In this demonstration the Motor drive is provided by the IDK over the three terminals of J17. If no encoder is used or an encoder is available and attached to the longer shaft of the motor, then the connections from the EVM to the motor are: The Red wire from the motor should be connected to J17-1. The Black wire from the motor should be connected to J17-2. The Yellow wire of the motor should be connected to J17-3. Alternatively, if the encoder is attached to the shorter shaft of the motor, then the connections from the EVM to the motor are: The Yellow wire of the motor should be connected to J17-1. The Black wire from the motor should be connected to J17-2. The Red wire from the motor should be connected to J17-3. The encoder should be to be connected to the onboard connector J10.

To test TI EtherCAT slave sample app - one can use TwinCAT or any other compatible EtherCAT master. Below are the steps to use TI slave with TwinCAT. Additional details on TwinCAT configuration can be found at here.

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 . Note, please always check ethernet adapter is listed below "installed and ready to use devices" before attempting to run TwinCat demo.
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 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. Alternatively, you can use "Toggle Free Run State" bottom.
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.
    On startup, the application will set digital out LEDs 1 to 8 to on . This indicates that slave is up and in the INIT state.
    
    
    
    Figure 2 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.
   
   
   
   Figure 3 TwinCAT LED Control Display
   

1. To control the Motor using TwinCAT.(Available in full application ONLY),
   1. The Motor speed is set by selecting  TI Boxn(ti-esc)>Motor Outputs->Data and selecting the Online tab. The speed can be set a value between 1000 (for 4000 rpm in the forward direction) and -1000 (4000 rpm in the reverse direction). This same Data field also serves as the position input (in position control mode). In the position mode, a 0 corresponds to 0 degree, while a 1000 corresponds to 360 degrees.
   2. The value is entered into the controller by selecting the Write button, entering a value, and selecting OK.
   
   
   
   Figure 4 TwinCAT Motor Control Display
   
2. The Command box permits the setting of the lsw variable.
   The Count box permits the setting of the msw variable.
   Please refer below to the block diagram for the illustration of the lsw & msw variable function.
   The default build level for the FOC motor control is LEVEL4 (closed speed loop with EnDat position feedback). The Build level can be changed using BUILDLEVEL in foc.h and then rebuilding the project. In LEVEL4, controlling variables are lsw and speed. The default value of lsw is 0. For an open speed loop set lsw to 1. Set lsw to 2 for a closed speed loop.
   
   
   
   Figure 5 TwinCAT FOC Level 4
   In LEVEL5, the controlling variables are lsw and angle. In this configuration, lsw = 0 (default) is the position control is turned off. To enable position control set lsw to 1 or 2. 1. As described earlier, the position is set by selecting TI Box (TIESC-00n) -> Motor Outputs -> Data and selecting the Online tab. The position can be set a value between 0 and 1000. A 0 corresponds to 0 degrees, while a 1000 corresponds to 360 degrees. The value is entered into the controller by selecting the Write button, entering a value, and selecting OK.
   
   
   
   Figure 6 TwinCAT FOC Level 5
   LEVEL6 is a combination of LEVEL4 & LEVEL5. In Level 6 the control variables are msw, lsw, speed and angle. When msw = 0 (default), the FOC is operating in speed control mode. In this mode, use the lsw and speed settings as discussed previously in LEVEL4. The angle input is not used in when msw = 0. To include position control set msw = 1. In this mode, the angle control operates as described in LEVEL5. In this configuration, the speed and lsw settings are ignored.
   
   
   
   Figure 7 TwinCAT FOC Level 6
   

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

LED Toggle

The 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 and act1 LED. 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 specific pattern.

This application is dependent on the drivers.lib, am437x_platform.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.

Motor Control

The Motor Control demo demonstrates a sensored 3 phase sensored Field Oriented Control (FOC) of a single Permanent Magnet Synchronous motor (PMSM) using the onboard AM437x ADCs and optionally the EnDat 2.2 master interface and a EnDat encoder attached to the motor. The FOC algorithm provides smooth speed control, with high dynamic performance. The FOC algorithm transforms the 3 phase AC current measurements to d-q axis values allowing control of torque and flux. This application requires that the USB port of the EVM is connected to the host PC to enable a UART over USB connection between the EVM and host PC. A serial terminal application (like teraterm/ hyperterminal/ minicom) is then run on the host. To configure the terminal, select the serial port corresponding to the port emulated over USB by the EVM. The host serial port should be configured to 115200 baud, no parity, 1 stop bit and no flow control.

The Motor drive is provided by the IDK over the three terminals of J17. If no encoder is used or an encoder is available and attached to the longer shaft of the motor, then the connections from the EVM to the motor are: The Red wire from the motor should be connected to J17-1. The Black wire from the motor should be connected to J17-2. The Yellow wire of the motor should be connected to J17-3. Alternatively, if the encoder is attached to the shorter shaft of the motor, then the connections from the EVM to the motor are: The Yellow wire of the motor should be connected to J17-1. The Black wire from the motor should be connected to J17-2. The Red wire from the motor should be connected to J17-3. The encoder should be to be connected to the onboard M12 connector J10.

The Motor control application has been validated using a Permanent Magnet Motor (BLY171D-24V-4000, Anaheim Automation). This is coupled to an EnDat 2.2 encoder (ROQ 437, Heidenhain). The motor can be controlled via terminal console. If an EnDat encoder is attached - Upon executing the run command the terminal window will display.

Figure 8 EnDat Display when Encoder is Attached
If an EnDat encoder is not attached - Upon executing the run command the terminal window will display.

Figure 9 EnDat Display when Encoder is Not Attached

Upon pressing enter in the console, user will be asked to enter motor control variables. Simply pressing enter will bypass the setting of any variable. This is helpful, especially when only one variable needs to be changed. The meaning of these variables will change slightly with each of the different build levels. The default build level is LEVEL4 (closed speed loop with EnDat position feedback). The Build level can be changed using BUILDLEVEL in foc.h and then rebuild the project.

In LEVEL4, controlling variables are lsw and speed. The default value of lsw is 0. For an open speed loop set lsw to 1. Set lsw to 2 for a closed speed loop. The motor, BLY171D-24V-4000, has a maximum speed of 4000 RPM. The desired speed can be expressed as an RPM value in the range of 0 to 4000. To reverse rotation, a negative value is entered. In LEVEL5, the controlling variables are lsw and angle. In this configuration, lsw = 0 (default) is the position control is turned off. To enable position control set lsw to 1 or 2. The desired position can be specified as an angle in the range 0-360 to control the position.

Figure 10 FOC Level 4
In LEVEL5, the controlling variables are lsw and angle. In this configuration, lsw = 0 (default) is the position control is turned off. To enable position control set lsw to 1 or 2. The desired position can be specified as an angle in the range 0-360 to control the position.

Figure 11 FOC Level 5
LEVEL6 is a combination of LEVEL4 & LEVEL5. In Level 6 the control variables are msw, lsw, speed and angle. When msw = 0 (default), the FOC is operating in speed control mode. In this mode, use the lsw and speed settings as discussed previously in LEVEL4. The angle input is not used in when msw = 0. To include position control set msw = 1. In this mode, the angle control operates as described in LEVEL5. In this configuration, the speed and lsw settings are ignored.

Figure 12 FOC Level 6

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:It is recommended to bring motor to a standstill before connecting/disconnecting through JTAG

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 verify that the motor is at a standstill

NOTE 4:Use power supply provided with AM437x IDK

ADC sampling firmware using ICSS0_PRU1

This firmware makes use of the PRU C compiler assembler and linker integrated in CCS6.x onwards. Additional detail on that is available is contained the following documentation.

PRU Optimizing C/C++ Compiler v2.0, http://www.ti.com/lit/ug/spruhv7/spruhv7.pdf PRU Assembly Language Tools v2.0 User's Guide http://www.ti.com/lit/ug/spruhv6/spruhv6.pdf

sdk\interfaces\pru_onchip_adc_sampling\firmware has the example firmware implementation for ADC sampling and PWM & ADC synchronization

• icss_cfg_regs.hp: Register offsets for PRU_ICSS_CFG registers
• icss_cntl_regs.hp: Register offsets for PRU_ICSS_CTRL registers
• icss_ecap_regs.hp: Register offsets for PRU_ICSS_ECAP registers
• icss_event_defs.hp: PRU_ICSS system event defines
• icss_iep_regs.hp: Register offsets for PRU_ICSS_IEP registers
• icss_intc_regs.hp: Register offsets for PRU_ICSS_INTC registers
• icss_regs.hp: PRU_ICSS local memory map defines and Constant table entries

For more details on above, refer to AM437x TRM Chapter 30

• pru_adc_sampling_macros.hp: Reference macro implementations for legacy pasm CALL and RET instructions using clpru macros
• pru_adc_sampling.hp: Various configuration and register variable defines for ADC sampling firmware
• pru_adc_sampling.asm: Main assembly source file which implements ADC sampling and PWM to ADC synchronization using IEP timer module
• pru_adc_sampling.cmd: Command file for clpru linker (generates .out file from .obj files)
• pru_adc_hexpru.cmd: Command file for hexpru tool (generates .bin file from .out file)
• build_pru_adc_sampling.bat Bat file to build firmware C array header from assembly input files. Set PRU_C_COMPILER_PATH to PRU C compiler tool path

E.g.:-"C:\ti\ccs6\ccsv6\tools\compiler\pru_2.0.0B2") .project,.ccsproject, .cproject: CCS 6.x project files to build .out (for debugging firmware) and C array header (to be included in applications) from assembly sources

NOTE: sdk\tools\bin2header\bin2header.exe generates pasm compatible PRU firmware C array header from hexpru generated .bin files. Source code for the same is available in the same folder. Usage : bin2header.exe input_binary_file output_C_header_file output_array_name 4/1 [4: 32-bit hex values 1: 8-bit hex values (default)]

PRU ADC sampling firmware Host interface

Maintained in ICSS0 PRU1 Data memory (base address: 0x54442000)

• FOC_CONTROL_OFFSET(0x54442050): Indicate to PRU firmware when Host is ready for FOC processing 0: Wait 1: Continue
• FOC_TRIGGER_OFFSET(0x54442054): Select when to issue End of Conversion (EOC) to Host. On ADC EOC event (FOC_TRIGGER_IS_ADC) or on ADC EOC & EnDat EOC event (FOC_TRIGGER_IS_ENDAT). FOC_TRIGGER_IS_ADC is used today
• FOC_IEP_PWM_PERIOD_OFFSET(0x54442058): Configure the PWM_PERIOD for ICSS0 to track and synchronize the ADC events w.r.t PWM period (nano sec units)
• FOC_IEP_ADC_SOC_TRIGGER_OFFSET(0x5444205C): Configure ADC_SOC trigger time period from host (nano sec units)
• FOC_IEP_ENDAT_SOC_TRIGGER_OFFSET(0x54442060): Configure ENADT_SOC trigger time period from host (nano sec units)
• FOC_IEP_PWM_SYNC_OFFSET(0x54442064): Adjust IEP counter w.r.t PWM counter, program the IEP counter init value when PWM counter is cleared during synchronization phase (nano sec units)

PRU ADC sampling firmware overview

The Host will setup the PRU_ICSS INTC mapping, initialize PRU memories, initialize firmware configuration variables, download and start the firmware execution…

Init:

1. Firmware clears all registers and wait for Host interface to be ready polling FOC_CONTROL_OFFSET
   
2. When host CPU is ready, firmware initialize IEP CMP registers with PWM_PERIOD, ADC_SOC_TRIGGER, IEP_PWM_SYNC values programmed by host.
   
   1. PWM_PERIOD (CMP0) is 100000 (100us ) for 10 KHz
      
   2. ADC_SOC_TRIGGER (CMP1) is 50000 (50us) - mid point in PWM cycle
      
   3. IEP_PWM_SYNC is set to 50000 (50us)
      
3. Clear all pending events for ADC, PWM, IEP and INTC
   
4. Align PWM_TBCNT and IEP_COUNTER based on IEP_PWM_SYNC
   

Main loop:

1. Firmware poll for IEP_CMP_HIT event, if match and ADC_SOC_TRIGGER (CMP1) then generate ADC_SOC via ICSS0_HOST5 > ICSS1_HOST0 >ADC1_EVT_TRIGGER connection
2. Firmware poll for ADC_EOC event (from ADC register) if match then read samples from ADC FIFO, store to PRU data memory in required format and generate ADC_EOC to host cortex A9

Field Oriented Control (FOC)

The Field Oriented Control (FOC) algorithm is used to control the motor. This implementation is derived from the C2000 PMSM sensored servo FOC.

The FOC implementation used in this application has 6 LEVEL's. LEVEL4 and LEVEL5 are the ones that would normally be used in most applications. LEVEL3 and LEVEL6 are included primarily for demonstration purposes. LEVEL1, 2 and 3 are used during system bring up and tuning.

Description of different 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 performed at runtime

Position Offset Compensation

The position value reported by encoder at zero electrical angle of the motor has to be set to zero. The position offset compensation value helps in correcting it. Position offset compensation between motor and encoder can have different values with a relative angular position between them. There are two methods to determine the poc as follows,

1. A reliable, precise (and difficult) means to determine the poc is to incrementally change the position offset compensation and find the value at which q-axis value (at memory location 0x54442204) and the d-axis value (at memory location 0x54442104) current drawn is minimum.

2. Poc quick estimate for a coupled motor and encoder set – automatically detected poc value is available in memory location 0x54442030 as a floating point number. This is available within a second of the time that the motor has started running in a closed speed loop (lsw = 2) at LEVEL4. Repeat this step for 10 times (restart every time), and note down the poc value for all the cases where motor runs properly till 75% rated speed. Some times motor may go out of step or over current may happen, discard the values in those case. Average the value for successful cases.

Once the position offset compensation value is obtained, using either of the above methods, replace the following code in foc.c,

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

TO:

_iq OffsetE = _IQ(<new position offset compensation value>);
Uint32 ElecThetaCalibrateFlag = 1;

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

PI Tuning

The FOC algorithm uses several PI controllers. For a given setup, it may be necessary to tune the current, speed and position PI controller parameters. These variables are exposed through the PRU shared memory, which is modifiable at runtime using CCS. To change these values, first go to the CCS debug window. To enable the Non Debuggable Devices display, right click on AM437x_XDS100V2.ccxml [Code Composer Studio - Device Debugging] and select “Show all cores” . Then select Texas Instruments XDS100v2 USB Emulator_0/CS_DAP_DebugSS 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

The 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

The 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 provided in $(IA_SDK_HOME)\Examples\EtherCAT folder is a limited development application. To have a full development capability on the AM437x, it is necessary to get the EtherCAT source code from Beckhoff and use that with the SDK example application. The SDK example application provides all board specific implementation sources for EtherCAT and a patch file to modify Beckhoff source files for the 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 the 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 application should work with another ESI xml file, user will need to generate a corresponding ESI header file ( tiesc_eeprom.h ) and re-build the 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 :
'bin2header.exe 'binary_filename' 'header_filename'

Example:
bin2header.exe "C:\Documents and Settings\user\Desktop\Box1.bin" "C:\Documents and Settings\user\Desktop\tiesc_eeprom.h" br>

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

Building Bootloader

Boot loader project is included in the starterware package. The supported build configurations for AM437x are:

1. am43xx_boot_mmcsd_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
2. am43xx_boot_mmcsd_release - This configuration is optimized to an extent. Builds binary to be executed from SD card
3. am43xx_boot_qspi_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 qSPI flash
4. am43xx_boot_qspi_release - This configuration is optimized to an extent. Builds binary to be executed from qSPI 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\bootloader directory to CCS. See importing and building instructions section for details.
• Import dependent starterware projects. They are board, dal, soc, utils, ff9b_lib and mmscd_lib. They can be located at $(IA_SDK_HOME)\starterware\
• Select the appropriate build configuration for the bootloader. The dependent projects will automatically build
• Set predefined macros as follows
• Set the post build script arguments properly. See Post Build Script section for details.
• Build bootloader project.

A Successful build will generate boot.out and binary file in $(IA_SDK_HOME)\starterware\binary\bootloader\bin\am43xx-evm\ccs\

Generating Executable Binary - Post Build Script

OBJCOPY is used to generate a binary(.bin) from a .out file. Then isdk_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 - isdk_image.exe path
• Param 6 - Load address for the binary in hexadecimal format.
• Param 7 - Run address for the binary in hexadecimal format. (Address of _c_int00 in the generated .map file)
• 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}/tools/isdk_image/isdk_image.exe" "0x80000000" "0x800164cc" "NONE"
"${workspace_loc:/${ProjName}}/Debug/ecat_appl.bin"
"${workspace_loc:/${ProjName}}/Debug/ecat_appl_ti.bin"

Technical Support and Product Updates

The support and comunity for Sitara Processors is at http://www.ti.com/lsds/ti/arm/sitara_arm_cortex_a_processor/support.page The Sitara E2E forum is at http://e2e.ti.com/support/arm/sitara_arm/default.aspx