TMS320C2000 Motor Control Primer 1

TMS320C2000 Motor Control PrimerHigh-performance drive applications require fast, reliable, and robust control systems. Therefore, there is asignificant demand for well-equipped digital motor control (DMC) platforms to educate the next generation ofengineers. In this users guide, a number of introductory-level digital motor control methodologies and laboratorytools are presented. These tools help engineers learn how to easily construct their own systems using TI provideddevice drivers, APIs, utilities, and libraries. Also described is Texas Instruments' motor control developer’s kits,software framework, and DMC library. These documents provide a modular development strategy which allows theuser to experiment incrementally from a basic to an advanced level.

IntroductionDigital motor control has been a challenging subject since the beginning of early implementations. Although digitalcontrol techniques and the availability of high-speed microcontrollers made life significantly easier for engineers,highly non-linear motor models, designing and tuning multiple control loops, math intensive sensorless algorithms,parameter and temperature dependencies, and complex software structures still have the potential to slow downdevelopment.Texas Instruments understands the challenges facing motor control developers, and provides materials and tools thatsignificantly accelerate development and troubleshooting of motor-control systems. Thorough documentation, a richset of digital motor control and math libraries, modular software strategies, incremental build processes, codedevelopment environments with real time debugging support, and sample motor control kits at different voltagelevels designed for all major motor types with open source hardware support, lead developers through the process ofcreating a complete motor-control system. These tools enable developers to quickly determine the processingresources required to implement basic motor control. From this baseline, they are then able to bring in advancedalgorithms to trade-off the remaining processing capacity for greater accuracy, better performance, and higher powerefficiency, control of multiple motors or integrated power stages like digital power factor correction, and a myriad ofother options. In this way, developers can architect systems specifically optimized for their application constraintsand requirements.

Software Tools

IQ Math Library

What is IQ Math LibraryReal-time control algorithms used in industry are typically computationally intensive, where optimal execution speedand high accuracy is required. When C is used to develop control algorithm code, generic math libraries can be usedfor computing math functions such as trigonometric functions, division, etc. However, this approach may not resultin the most cycle efficient code. Therefore, TI provides a library of highly optimized and high precision mathfunctions in the form of the IQMath library. Using the math routines in the IQ Math library the user can achieveexecution speeds considerably faster than equivalent code written in standard ANSI C language.The IQ Math library is available in both fixed-and floating-point versions, enabling easy migration from float tofixed devices. The fixed-point library uses Q-arithmetic to emulate the fractional point (explained in the followingsection), whereas the floating-point version uses the floating-point instruction set and hardware FPU present on thedevice.

TMS320C2000 Motor Control Primer 2

Q Format and Preferred Global Q for DMCQ Format is a way of representing a numeric value containing a sign, integer and fraction portion in a fixed bitlocation field. Figure 1. The following image illustrates a 32-bit binary number where the bits are partitioned torepresent the sign, integer, and fractional parts.

Figure 1. Sign, Integer, Fractional Parts

whereS: Sign Bit (1 bit)I: Integer Bits (7 bits)F: Fraction Bits (24 bits)Thus, the fixed bit location acts as a virtual floating point. The IQ Math library makes use of such a representation tocompute the functions on a fixed-point device. The IQ Math library further allows the user to select the appropriatenumeric range and resolution by choosing where the decimal point is located, i.e., how many bits of the binaryrepresented number are integers and how many are the quotient/fraction.A value of a number represented in the format above can be interpreted as:

The number of fraction bits determines the Q format of the number. For a given word length (e.g., 32 bits), thegreater the number of fractional bits, the higher the resolution, and the smaller the dynamic range. Table 1 showssome examples regarding the range and resolution of 32-bit, fixed-point numbers for different Q formatrepresentations.Table 1. Range and Resolution of 32-bit Fixed-point Number for Different Q-format Representation

GLOBAL_Q Max Val Min Val Resolution

28 7.999 999 996 -8 0.000 000 004

24 127.999 999 940 -128 0.000 000 060

20 2047.999 999 046 -2048 0.000 000 954

A high resolution and large dynamic range is typically needed for precise control algorithm execution. Motor controlapplications formats between Q31 to Q27 do not provide enough dynamic range, and formats of Q18 or lower resultin significant quantization errors, due to insufficient resolution. Therefore, a format of Q24 is used by the TI motorcontrol software because it provides enough high resolution and enough dynamic range to tackle a wide variety ofmotor applications. Note that all the motor control projects are implemented based on per unit (pu) system variablesand the Q used by these variables is by default, Q24. For floating-point devices, single-precision IEEE float is used.Also note that although the default Q is 24, the DMC library can be made to use any other Q format by changing theGLOBAL_Q value.

TMS320C2000 Motor Control Primer 3

Summary of the IQ Math FunctionsThe routines included within the IQmath library can be classified as:• Arithmetic/math functions (addition, subtraction, multiply, divide, etc.)• Trigonometric functions (sine, cosine, tangent, etc.)• Format conversion utilities (scales numbers from one Q format to another)• Miscellaneous (saturation, absolute value, etc.)Some of the IQmath library functions used often in motor control are shown in Table 2.Table 2. Some IQMath Functions Used Often in Motor Control Applications

C C++ Operation

_IQ(float) IQ(float) Constant

+ + Add

- - Subtract

_IQmpy * Multiply

_IQdiv / Divide

_IQsqrt sqrt Square root

_IQisqrt isqrt 1/Square root

_IQsin sin Sine

_IQcos cos Cosine

_IQatan atan Arc tangent

_IQatan2 atan2 Arc tangent 2 opr.

_IQsinPU sinPU Sine per unit

_IQcosPU cosPU Cosine per unit

_IQatan2PU atan2PU Arc tangent 2 opr. per unit

_IQsat sat Saturation

_IQabs abs Absolute value

Calling an IQMath Function in CThe IQ Math library is very user-friendly and comes with detailed documentation explaining the features and usageof each library function, along with example code. The following sample code shows how to write a Park transformfunction using IQ Math library trigonometric and multiplication functions:

#include "math.h"#include "IQmathLib.h"#define TWO_PI 6.28318530717959void park_calc(PARK *v){

_iq cos_ang, sin_ang;sin_ang = _IQsinPU (v->angle);cos_ang = _IQcosPU (v->angle);v->de = _IQmpy(v->ds ,cos_ang) + _IQmpy(v->qs ,sin_ang);v->qe = _IQmpy(v->qs ,cos_ang) -_IQmpy(v->ds ,sin_ang);

TMS320C2000 Motor Control Primer 4

}Note that in the above example, the variables are declared not as fixed or float but as “iq.” The iq type is interpretedat compile time, and is substituted for a fixed-or floating-point variable type, depending on the device type beingused. Consequently, the code above can be run on a fixed-point or a floating-point device without any changes,therefore enabling easy migration between floating-and fixed-point devices.

Advantages of the IQMath Library for Motor ControlIQmath uses the instructions present on the C28x™ devices in the most efficient way to compute the various mathfunctions. Briefly, the benefits and contributions of the IQMath Library in C2000™-based digital motor control canbe summarized as follows:• Selection of dynamic range and resolution on fixed point devices: For fixed-point devices, a choice of Q can

be made depending on dynamic range and resolution requirements of the system. Q24 is used by default but canbe changed easily to select another Q format if needed.

• Float to fixed migration: All the functions available in the floating-point version of the library are available onfixed-point version and vice versa; hence, migration from float to fixed becomes very easy. The use of “iq” typewhile writing code enables the compiler to interpret the math type to be used for the variables at compile time.Thus, no or little change is required to the source code when migrating from floating-to fixed-point devices.

• Highly optimized function: This function enables faster and multiple control loop execution than what ispossible using standard ANSI-C routines.

Digital Motor Control (DMC) Library

DMCLib OverviewThe digital motor control library is composed of C functions (or macros) developed for C2000 motor control users.These modules are represented as modular blocks in C2000 literature in order to explain system-level blockdiagrams clearly by means of software modularity. The DMC library modules cover nearly all of thetarget-independent mathematical functions and target-specific peripheral configuration functions, which are essentialfor motor control. These modules can be classified as:

Transformation andObserver Modules

Clarke, Park, Phase Voltage Calculation, Sliding Mode Observer, BEMF Commutation, Direct Flux Estimator,Speed Calculators and Estimators, Position Calculators and Estimators etc.

Signal Generators andControl Modules

PID, Commutation Trigger Generator, V/f Controller, Impulse Generator, Mod 6 Counter, Slew Rate Controllers,Sawtooth & Ramp generators, Space Vector Generators etc.

Peripheral Drivers PWM abstraction for multiple topologies and techniques, ADC Drivers, Hall Sensor Driver, QEP Driver, CAPDriver etc.

Real-Time DebuggingModules

DLOG module for CCS graph window utility, PWMDAC module for monitoring the control variables throughsocilloscope

In the DMC library, each module is separately documented with source code, use, and background technical theory.All DMC modules allow users to quickly build, or customize their own systems. The library supports three principalmotor types (induction motor, BLDC and PM motors) but is not limited to these motors.The DMC modules — implemented in IQmath — are used to construct both sensored and sensorless control systems. An earlier version of the DMC library (legacy) was released for the F281x series SPRC080 [1], and F280x series SPRC215 [2]. Starting in 2010, the libraries were revised with optimized macro usage for system examples using F2803x (Piccolo) and F2833x (Delfino) families and integrated into controlSUITE [3]. For more on the motor control methodology and available resources, visit the TI Motor [4]Control Site [4]. There are two releases of the math_blocks in controlSUITE; the fixedv1.1 supports all three motor types and is only valid for fixed processors.

TMS320C2000 Motor Control Primer 5

The v2.0 supports both fixed (all) and float (induction motor and PM motors) system examples.The DMC library components have been used by TI to provide system-level motor control examples. In the motorcontrol code, all DMC library modules are initialized according to the system specific parameters, and the modulesare inter-connected to each other. At run-time the modules are called in order. Each motor control system is builtusing an incremental build approach, which allows some sections of the code to be built at a time, so that thedeveloper can verify each section of the application one step at a time. This is critical in real-time controlapplications, where so many different variables can affect the system, and where many different motor parametersneed to be tuned.

Incremental System Build MethodologyIt is well known that, regardless of how much planning has gone into a system engineering project; chances are thefinal system won’t work for the first time, usually because some subtle target dependency or requirement has beenoverlooked. This is normal engineering, and if a contingency plan or debug methodology has been comprehended,it’s not a problem. However, if not anticipated ahead of time, this can become frustrating and time-consuming. Toprevent this, the system comes pre-packaged within a framework, incorporating various system build levels or debugsteps as part of the normal system software flow. A customer can move from a current build level to any other buildlevel quickly, and without risk of losing configuration or run-time information related to previous build levels.This framework also allows a user to commission system software in a step-by-step manner, and at each step validatekey vital signs before moving on. The number of build levels may vary depending on final system complexity, but animportant point to note is that regardless of the number of build levels, this framework becomes a common point ofreference. In either case, it will greatly improve the chances of system software success. As will be seen later,incremental system build levels are supported by frameworks with various configurations of interconnected modules.Frameworks also provide invaluable skeletons for users to modify or customize as required to suit their own targetsystem requirements.

Well Defined Module Variables Provide Clear Debug PointsBecause the system/module framework has one-to-one mapping with the system signal flow diagram, it is easy toprobe signals of interest and to visualize them in real time. TI provides useful utility modules which can displaytime-varying signals (i.e., software variables) via hardware DAC using an oscilloscope, or on screen with CodeComposer Studio™ using a data-logging software module. The PWMDAC and DATA_LOG modules can be readilyconnected by way of pointers during run-time, to any module terminal variable and internal module variables forgreater software visibility.

Known Working Library Eases the DevelopmentModules can provide a valuable starting point, even if they are not exactly the final requirement. Known goodmodules can be used initially on a “trust-for-now” basis as a system is built up and valuable experience is gained.Later on, these standard modules can be investigated on an as-needed basis, to learn more, or to modify or customizeto suit. A modular approach is ideal for this, allowing standard modules to be swapped out for customized ones lateron without risk or delays.

2Code Composer Studio and Documentation Completes the PackageThe solutions collateral outlined so far for the digital motor control systems software is comprehensive with many component parts. To bring it all together and to allow customers to test drive many solutions quickly, TI offers Code Composer Studio™ (CCS) for the C2000 platform as the Integrated Development Environment (IDE). Ready-to-run CCS projects and workspaces ensure customers are jump-started into productivity quickly. To complement the IDE, clear module and system documentation tie the solutions together and help customers understand how theory,

TMS320C2000 Motor Control Primer 6

implementation, and debug all come together to provide a working solution.

Software ModularityThe benefits of structured, modular software are well known. This is especially true for large, complex systems withmany sub-blocks contributed by many individuals. In these cases, there is a strong common set of needs. Efforts bycontributors should only be used one time, and are reusable for future projects. The contributed software blocks(modules) must be predictable in their behavior and compatible with other blocks, both functionally and numerically.Industry has learned the benefits of these methodologies, and has realized the impact they can make on smoothersystem integration; reducing debug and troubleshooting time, providing a higher degree of visibility inside thesoftware, and allowing quicker system reconfiguration. These attributes have significant impact on getting qualityproducts out to market in a timely manner.Such methodologies needed to be applied to high-performance motor control systems and to address this, TIintroduced the modular DMC library in early 2000. Within the digital control systems space, the algorithm standardhas been used to address the specific needs of application areas such as digital motor control, industrial electronics,uninterruptible power supplies, plus a host of other control-related areas. The familiar signal flow block diagramrepresentation of digital control systems, as seen in control texts and university publications, lend themselves well toeffective implementation by software-interconnected module blocks (i.e., functions or macros) with well-definedinput and output ports.Once a rich set of library modules is available with a well-defined and proven interconnect methodology, systemscan be realized fairly quickly. The logical extension is that various “what-if” scenarios of system topologies and/orconfigurations can be explored relatively easily and with little overhead. As a more basic or fundamental need, thissame ease of module connection allows a system designer to have a number of incremental build levels, rangingfrom a rudimentary system (3-4 modules) used to check out key life signs, to a fully featured final system with alarge number of connected modules. This is analogous to the commissioning steps or process which is typical inlarge engineering projects. This approach to system software commissioning is invaluable during the systemintegration phase and can greatly reduce the time and effort required.

Consistency Between Software Modules and Control Block DiagramsIt is well known that systems and control engineers like to visualize systems or control strategies in the form ofsignal flow block diagrams. It makes good sense to separate main functions and to show how each is interrelated byexplicit connection to other functions. Each function should be self-contained, and its boundaries or interface clearlydelineated. A digital motor control system is a good example of this interrelation of functions. Figure 2 shows atypical signal flow block diagram of an AC induction motor controlled by a field-oriented control strategy. This is auseful representation, and it is found in many classical texts on motor control. However, several limitations areevident when attempting to realize this diagram in software form.

Figure 2. ACI Sensored FOC -System Block Diagram

TMS320C2000 Motor Control Primer 7

It is not usually clear how software variables are related to the signal parameters on the diagram, nor where in thesoftware these parameters can be found and accessed. Moreover, the boundary between software and hardware isblurred (i.e., where the software controls the on-chip peripheral and where the peripheral output pins control theexternal hardware, such as the PWM-to-inverter interface). By adopting a modular strategy and enforcing some cleardefinitions, the classic block diagram shown in Figure 2 can be rearranged and redrawn to reveal a great amount ofinformation about the actual software which is used to implement such a system. This new style of systemrepresentation can be seen in Figure 3. The advantages and features of such a representation will be expanded uponin later sections, but a summary of key points are given here:• The system block diagram has a clear one-to-one mapping to the modular system software.• Each module graphic or block represents a self-contained software function or object of the same name.• Input and output terminals of each module correspond exactly to global variables within the software function.• Modules are categorized (color coded) to clearly designate dependencies on peripherals and target hardware.• Connections between modules show data flow via corresponding input/output variables.• Each module is reusable and has its own documentation explaining usage and instantiation.

Figure 3. ACI Sensored FOC – System Block Diagram Showing Clear One-to-One Mapping to Software

TMS320C2000 Motor Control Primer 8

Reusability, Compatibility, and ExpandabilityEngineering reuse in today’s competitive environment is critical and software modularity is the perfect vehicle toachieve this, especially in DMC systems. If we examine various motor control systems, it becomes clear that a largedegree of commonality exists between them. The PID regulator, for example, is useful across all systems. Therefore,if each module is realized only once, but implemented according to well defined guidelines, then compatibility andpredictability can be assured across all modules. Since this approach allows efficient reusability, efforts which maytypically be used to “reinvent the wheel” can be re-deployed on expanding the module library base for greaterfunctionality and features.There are several DMC blocks common for 3-phase motor control in general. On the other hand, in most cases, thedifference between a sensored and sensorless system is only one or two modules, e.g., a position or speed estimator.The remaining modules are again common. Therefore, in keeping with the reuse philosophy, design efforts can befocused on expanding the library with more robust estimators which meet various system requirements, rather thanrecreating entire system infrastructures.

Target Independent Modules and DriversUnderstanding the exact dependencies of a software module is very important. This knowledge is invaluable duringdebugging, software porting from one target to another, and on planning a system commissioning strategy. Themodules which are part of the DMC Library (examples of which are shown in Table 3) are categorized into two maintypes:• Target (microcontroller) independent (TI)• Drivers (i.e., target dependent and application configurable)Table 3. Sample of DMC Module Descriptions and Type Category

TMS320C2000 Motor Control Primer 9

Number Module Description Type

1 bldcpwm_drv BLDC PWM driver – uses high-side chopping and fixed on/off for low side Drv

2 cap_event_drv Capture input event driver Drv

3 hall_gpio_drv Hall effect interface driver for sensored 3-phase BLDC trapezoidal control Drv

4 pwm_drv PWM driver (configurable for active high/low, dead-band, or asm/sym) Drv

5 bdc_pwm_drv Brushed DC-Motor PWM driver Drv

6 qep_theta_drv Quadrature encoder pulse interface driver with position (theta) as output Drv

7 qep_no_index_drv Quadrature encoder pulse interface driver without index pulse Drv

8 ileg_vdc Analog to digital conversion drive Drv

9 resolver_drv Position and speed calculations for resolver sensor Drv

10 data_log Data logging utility – useful for variable graphing in code composer Util

11 pwm_dac_drv 4-channel DAC driver useful for displaying real-time variables on scope Util

12 aci_fe Flux estimator for 3-phase induction motor vector control TI/AC

13 aci_se Speed estimator of the 3-ph induction motor TI/AC

14 clarke Clark transform – 3-phase to 2-phase (quadrature) conversion TI/AI

15 comtn_trig Commutation trigger for BLDC sensorless trapezoidal/BEMF/ZC tech. TI/AC

16 cur_mod Rotor flux position estimator for 3-phase induction motor vector control TI/AC

17 i_park Inverse park transform – Rotating to stationary reference frame conversion TI/AI

18 impulse Impulse generator module TI/AI

19 mod6_cnt Modulo 6 counter counts from state 0 through 5 and reset TI/AI

20 park Park transform – Stationary to rotating reference frame conversion TI/AI

21 phase_volt_calc 3-phase voltage recontruction function based on PWM duty cycle inputs TI/AI

22 pid_reg3 Proportional/integral/derivative controller with anti windup feature TI/AC

23 ramp_gen Sawtooth generator with adjustable gain, frequency and dc offset TI/AI

24 rmp2cntl Ramp up and ramp down module TI/AI

25 rmp3cntl Ramp down module TI/AI

26 rmp_cntl Ramp up and ramp down module used to control slew rate TI/AI

27 smopos sliding mode observer for position estimation in sensorless vector drives TI/AC

28 speed_est Motor speed estimator using the estimated rotor position TI/AC

29 speed_frq Speed calculator based on frequency measurement – tacho style method TI/AI

30 speed_prd Speed calculator based on period measurement between events TI/AI

31 svgen_dq Space vector generator function with quadrature control TI/AI

32 svgen_mf Space vector generator function with magnitude and frequency control TI/AI

33 v_hz_profile Volts/hertz profile for induction motor (voltage vs. frequency) TI/AC

For convenience, the module graphics throughout the documentation are color coded to help customers quicklyidentify a modules dependency within a system. Color designation is as follows:• Target independent/application independent: TI/AI yellow• Target independent/application configurable: TI/AC pale red• Drivers (target dependent/application configurable): DRV blue

TMS320C2000 Motor Control Primer 10

Examples of target independent modules are given in Figure 4 and Figure 5. Target independent modules do notdirectly access or modify control or status registers of any on-chip peripherals, i.e., target microcontroller-specificresources. These modules are dependent only on the CPU core. TI/AI modules are typically characterized bymathematical type functions (e.g., transforms, matrix operations, waveform generators, etc.). These functions arefixed and fairly standardized, and do not require configuration, knowledge of peripherals, or the end applicationitself. TI/AC modules also do not need knowledge of device peripherals, but do need to be configured depending onthe end application. Examples of these modules are PID controllers, position/speed estimators, voltage and currentmodels, etc.

Figure 4. Target and Application Independent Modules -Examples </center

Figure 5. Target Independent/Application Configurable Modules

On the other hand, driver modules are the interface between software and target microcontroller-specific peripheralhardware. Examples of such modules are shown in Figure 6. These modules have direct access to peripheral control

and status registers. Using these driver modules or taking them as a reference, one can easily develop applicationspecific drivers to configure microcontroller peripherals such as PWMs, ADCs, QEP, CAP etc., as required.

Figure 6. Target Dependent Drive Module

Utility/Debug ModulesUtility and/or debug modules are mainly used during the software development and debug process. Typically theyare removed at time of software completion; however they can also be left in the code for system diagnosis ifrequired during field tests or evaluation. Two examples of these modules are shown in Figure 7. These modulesallow the software designer to probe any of the system variables, and display them in real time via a scope or agraphical output within Texas Instruments' Code Composer Studio.

TMS320C2000 Motor Control Primer 11

The PWMDAC module allows the user to monitor waveforms of software variables through a scope, whileDLOG_VIEW provides a memory buffer with a trigger feature that allows Code Composer to display two graphicalwaveforms in real-time. Graphical waveforms are continuously updated via the JTAG debug link while thecustomer’s application software continues to run. Both JTAG and the real-time data flow are non-intrusive toapplication software running on any devices.

Figure 7. Utility/Debug Modules

Quick Module Evaluation and TestingApart from the more obvious benefits of software modularity previously described, some of the same ideas can beused to facilitate quick module testing or evaluation, i.e., checking how applicable or how a module performs.Additionally, it becomes easy to test several “what if” scenarios by simply reconnecting modules and evaluatingseveral alternatives. Figure 8 shows a “module under test” setup where a known input stimulus is applied. The inputstimulus and output response of this module under test can be conveniently monitored in real time on a scope via thePWMDAC or DLOG utility modules.Apart from evaluating or confirming operation of a known good software module, this technique is useful whendeveloping new modules. During debug, input stimulus signals can be swept over the entire input range to look forboundary condition problems or discontinuities in output response. It should be noted that this process is valid,provided known good stimulus modules are used as input signals. This technique allows a software designer to checkvalidity of variable ranges, and to ensure waveform integrity over a required frequency range and system samplingrates.

Figure 8. Testing and Evaluating Modules

TMS320C2000 Motor Control Primer 12

DMC Library Documentation SupportTI seeks to offer a rich selection of software examples and working systems which are clearly documented. One areawhich has received much attention and improvement is the description or documentation of application software.Through the use of software modularity, it is possible to delineate and give an unambiguous one-to-one mappingbetween a system block (signal flow) diagram and the actual software code in question. This, together with moduledocumentation for each software block, shows the customer clearly where each piece of software is, what it is doing,and more importantly, the parameters or variables being passed and executed upon. All TI applications which arepart of the software offering, now consist of module documents and system documents. System documents alwaysinclude the system block or signal flow diagram, which among control engineers, remains one of the most usefulcommunication tools.

Module Level DMC Library Documents

The pdf files included in the library folders provide necessary information regarding the modules. The outline of themodule documents is standard and can be itemized as follows:• Introduction: Describes the functionality of each module, and provides detailed information about modules

properties such as type, target devices, etc.• C Interface: Module declaration details, usage, examples etc.• Technical Background: Mathematical derivation of the module functionality.Figure 9 shows these library documents and their location in controlSUITE , both in the desktop and in the C:folders.

Figure 9. Library Documents and Their Location in controlSUITE

TMS320C2000 Motor Control Primer 13

As shown in Figure 10, a target independent transformation module is described and the module inputs/outputs areshown explicitly in the introduction part. In addition, module type, target devices, and related files are explained inthis section.

Figure 10. Snapshot of Typical Target Independent Module

Following the module description, all the necessary information is provided for C interface of the DMC module, theintroduction of which is shown below in Figure 11. This section explains the structure of the module object; name,

TMS320C2000 Motor Control Primer 14

description, and format of the module input and outputs. It also explains special constants and data types, moduleinitialization and usage, and pseudo code providing the information about the module usage.

Figure 11. Snapshot of First Part of C Interface Section

In the last section, theoretical background and mathematical derivations of the equations (if applicable) are providedto the user as shown in Figure 12. This section helps the user to understand the philosophy behind the module andallow the user to customize it properly.

Figure 12. Snapshot From the Theoretical Background Section (need equation)

TMS320C2000 Motor Control Primer 15

DMC Library OptimizationThere are several ways to optimize motor control systems for performance in terms of memory consumption andCPU cycles required to achieve the given task. TI suggests the following options to optimize the overall systemperformance:• Use of the optimization levels via the –o switch on the compiler• Use of inlining as a technique to increase speed of execution• Transforming functions in to inline code via macro expansionWhen a function is called separately, the function call must call the code at the appropriate address, followed by areturn statement when the function execution is completed. In addition, there is some overhead associated withsetting up a stack frame. In the case of a small function, this call and return overhead may be significant, comparedto the size of the function itself. In addition, when a function is inlined, the compiler can optimize the function incontext of the calling code.Another optimization is sometimes possible: to turn the function into a macro expansion. This allows the compiler tooptimize further under certain circumstances and produces less code, and consumes fewer cycles to execute. Thedisadvantage of this method is the code size increase if multiple expanded macros are implemented. However, forsingle motor control, both size and cycle wise macro modules have superiority to earlier versions where the code sizebecomes comparable for dual motor operation. One must note that the number of instruction cycles is much lower inany case.Unlike the DMC Library version in Legacy, the modules in controlSUITE are written in the form of macros for optimization purposes (refer to Optimizing Digital Motor Control Libraries, SPRAAK2 [5], for more details at TI website). It is reported that the macro versions of the DMC library let the system run 2-3 times more efficient than non-optimized version in Legacy. The macros are defined in the header files. The user can open the respective header file and change the macro definition, if needed. In the macro definitions, there should be a backslash ”\” at the end of each line as shown below which means that the code continues in the next line. Any character including

TMS320C2000 Motor Control Primer 16

invisible ones like “space” or “tab” after the backslash will cause compilation error. Therefore, make sure that thebackslash is the last character in the line. In terms of code development, the macros are almost identical to Cfunction, and the user can easily convert the macro definitions to inline C functions. As an example, the parktransformation macro definition is shown below.

Figure 13. A Typical Module Declaration and Macro Definition

Incremental Build MethodologyIrrespective of how much planning has gone into a system engineering project, the chances are that the final (orcomplete) system will not work the first time, usually some subtle (or not) target dependency or requirement hasbeen overlooked. This is normal engineering, especially in the case of software development, and if not anticipatedahead of time, can become a frustrating and time consuming disaster.To prevent this, TI’s DMC Library system software comes prepackaged within a framework, incorporating varioussystem build levels or debug steps as part of the normal system software flow. A customer can move from a currentbuild level to any other build level very quickly and without risk of losing configuration or run-time informationrelated to previous build levels. This allows a customer to commission system software in a step-by-step manner, andat each step validate key vital signs before moving on. The number of build levels may vary depending on finalsystem complexity and the type of control strategy used. It is important to note that regardless of the number of buildlevels used in the reference system, this framework is provided by TI as guidance and becomes a common point ofreference in cases where customer trouble shooting necessitates interaction with TI customer support engineers.Incremental system build levels are supported by frameworks with various configurations of interconnectedmodules. Frameworks also provide invaluable skeletons for customers to modify or customize as required to suittheir own target system requirements, forming an excellent starting point.To better understand the philosophy and details of the incremental build approach, a typical motor control case, apermanent magnet synchronous motor, will be used to step through the various commissioning phases. The systemshown in is the final build of a sensored PMSM project. The subsequent block diagrams (Figure 14 to Figure 17)

TMS320C2000 Motor Control Primer 17

show examples of typical steps used to get to a solidly working final system.

Check System Vital Signs—Build Level 1Figure 14 shows the module configuration of build level 1. Although the first is the simplest build, it is perhaps themost important one since many system fundamentals can be validated here. Build 1 removes main externalconnections (power hardware, motor, feedback circuitry, etc.) and allows a customer to focus on:• Code compiling/linking using a Code Composer Studio (CCS) project• Invoking and downloading to the CCS debug environment• Setting up or importing a CCS workspace• Running code in real-time mode• Ensuring the hardware is functioning correctlyAssuming the above check list is correct, some key system vital signs can now be validated:• Check Interrupt Trigger: The sensored PMSM project, like most other DMC systems, is an interrupt driven,

time sampled system, meaning that the modules shown in Figure 14 are executed and updated on every interrupt.The Isr_Ticker, a software variable in the interrupt subroutine (ISR) behaves like a counter, and it is updatedwhen an interrupt is triggered and the code in the ISR is executed. In order to confirm that the ISR is beingtriggered at each selected event, this variable can be added to the watch window to see whether or not it isupdating.

• Testing some target independent modules: Validating both the stimulus waveforms (output of RAMP_GEN),and output of SVGEN via the PWMDAC utility or graph windows confirms system interrupts are being generatedand the main ISR is executing correctly. At this stage, the RAMP_GEN function can be manipulated via CCSwatch window to change its frequency and to see the corresponding changes on the waveforms.

• PWMDAC utility test: To monitor internal software variables and signal waveforms in real time PWM DACsare very useful tools. Present on the HVDMC board are PWM DAC’s (PWM5-7) which are connected to externallow pass filters to generate the waveforms. A simple 1st–order low-pass filter RC circuit is placed on the board tofilter out the high frequency components. The selection of R and C value (or the time constant, t) is based on thecut-off frequency (fc). For example, R=1.8kΩ and C=100nF, it gives fc = 884.2 Hz. This cut-off frequency has tobe below the PWM frequency. Refer to Using PWM Output as a Digital-to-Analog Converter on aTMS320F280x, SPRAA88A for more details.

• Check PWM outputs and verify PWM configuration: In addition, it is important to verify that the space vectorsignals (Ta, Tb, and Tc) are correctly modulating the PWM outputs. This is easily checked by filtering orsuppressing the high frequency carrier (typically 10–20 kHz) at the PWM output pins by a simple RC filter withapproximately 1 kHz cutoff. The filtered waveforms should then resemble the unmodulated ones seen at variablesTa, Tb, and Tc using the PWMDAC module. We now have a working forward path for the PMSM controllerrunning in open loop, and are ready to connect the power inverter hardware and motor.

• Inverter test: After verifying SVGEN module, the PWM software module and the 3-phase inverter hardware aretested by looking at the low pass filtered PWM outputs. For this purpose, if using the external DC power supply,gradually increase the DC bus voltage and check the Vfb-U, V and W test points using an oscilloscope; or if usingAC power entry slowly change the variac to generate the DC bus voltage. The inverter phase voltage dividers andwaveform monitoring filters enable the generation of the waveform. This circuit is used to observe the low-passfiltered phase voltage waveform to make sure that the inverter stage is working properly.

Figure 14. Build Level I - Checking Vital Signs

TMS320C2000 Motor Control Primer 18

Open Loop Motor Operation—Build Level 2In this level, the motor is connected to the inverter and the motor is run open loop. In this level, the items below willbe verified:• Open loop test: This is the first level that the motor is connected and run open loop. The user expects to set

VdTesting (a software variable which is supposed to generate the Vd and indirectly id component of the statorcurrent that produce flux) to zero since the flux will already be generated by magnets, and apply non-zeroVqTesting to generate torque. At this point, the motor should spin smoothly, indicating that the inverter hardwareis functioning properly. Since the field is not perfectly oriented and the current loops are not closed, it is notrecommended to load the motor or run it various speeds at this level in order not to lose synchronization or stallthe motor. Second, the test should initially be run under modest dc bus level for safety reasons. Once the userconfirms that everything performs as expected, then the dc bus can be increased to the rated value. During theopen loop tests, VqTesting, SpeedRef (speed reference) and DC Bus voltages should be adjusted carefully for PMmotors so that the generated Bemf is lower than the average voltage applied to motor winding. This will preventthe motor from stalling or vibrating. Therefore, tuning might be needed for VqTesting and SpeedRef for differentmotors.

• Verify and calibrate the ADCs measurements and check ADC configuration: It is necessary to make sure thatthe scaling factors of ADC measurements (voltage, current etc.) are set correctly, and that the dc offset caused bythe passive component tolerances is minimized. Note especially that low power motors draw low amplitudecurrent after closing the speed loop under no-load. The performance of the sensored/sensorless control algorithmsbecomes prone to phase current offset which might stop the motor or cause unstable operation. Therefore, thephase current offset values need to be minimized at this step. Since the current drawn by the motor is non-zero,the user should be able to monitor the current waveforms both from PMWDAC and CCS graph windows. If thecurrent waveforms cannot be monitored even though the motor spins, then the ADC configuration settings shouldbe double checked (such as channel selection, ADC system clock enable, etc.).

• Check the Clarke transform & current waveforms: With the motor running in a stable state, it is possible tovalidate the current measurement feedback path. The peripheral driver ILEG2_DRV helps the user configureADC and measure 2 inverter leg currents and reconstructs the motor phase currents. The 120o phase currents aretransformed to 90o quadrature currents by the CLARK transform module. Using PWMDAC or graph window,the shape, phase and quality of the current waveforms can be inspected. The Clarke alpha component should beleading Clarke beta if everything is set correctly, otherwise the user will not be able to run the next level and closethe current loop.

Figure 15. Build Level II - Inverter Test and ADC Calibration

TMS320C2000 Motor Control Primer 19

Closed Current Loop Operation—Build Level 3Assuming the previous section is completed successfully, this section verifies the dq-axis current regulationperformed by PID_REG3 modules, QEP drv and speed measurement modules.• Current regulator (PID modules) test and tuning: 3-phase motor control mainly consists of two main control

loops: a current loop and a speed loop. At this level, current control PIDs will be tested and tuned if needed. Aftera successful tuning, the user should make sure that the feedback currents precisely follow the Id and Iq currentreferences. While testing the PIDs, the dc bus voltage should not be too low; otherwise the outputs of the PIDmodules saturate which might introduce unwanted glitches on the current waveforms or unstable operation. Oncea stable set of PID coefficients is found, the transient response of the PIDs should be examined by changing Iqand Id references (IqRef and IdRef respectively). This has to be repeated for various load and speed conditions.Most of the time a single set of coefficients does not perform well at all operating points; therefore an operatingpoint dependent PID coefficient look-up table may be used to improve performance.

• QEP drv test: Build 3 also implements the angular position sensor feedback path, based on the QEP drivermodule which outputs both the mechanical and electrical angles. The optical position sensor and QEP interfacedriver are operating correctly when, while the motor is spinning, variable theta_elec can be viewed on the scope.Its output waveform should correspond in shape to the stimulus theta angle generated by the RAMP_GENmodule. This indicates that position information is being measured correctly.

• Speed measurement module test: The speed measurement module, SPEED_FRQ, is in the feedback path andcan also be validated at this stage. The speed measurement is dependent on motor shaft rotation, and theSPEED_FRQ module is driven from the theta_mech output of QEP module. Since its output value should beconstant, i.e. the motor is running at constant synchronous speed, the calculated speed, speed_frq, can be viewedvia a watch window instead of on the scope. The RAMP_GEN frequency can be increased slowly up or down tocheck whether the speed measurement varies appropriately.

• Calibration angle detection: In level 3, a simple calibration angle detection subroutine is added into the code tomeasure the initial angle offset. This is necessary because the exact rotor position information is needed forprecise field orientation. The detected offset angle is basically the angle between the locked rotor (zero) positionand the position where the first index signal is received.

Figure 16. Build Level III - Closed Current Loop Test

TMS320C2000 Motor Control Primer 20

Closed Speed Loop Operation—Build Level 4In this level, the speed loop will be closed in addition to the current loops regulating stator current d-q componentsand use the actual rotor position. This section verifies the speed PID and FOC based on actual rotor position. Thebasic sensored, field-oriented control of PMSM motor implementation will be done once this step is completedsuccessfully.• Torque control: If the user is interested in “torque only” control, the previous scheme allows the user control the

torque as long as the actual rotor position sensed by the QEP drv is fed to the Park and IPark transforms. Theamount of the load determines the speed of the motor at a given torque reference since the torque controlguarantees constant torque production but cannot control the speed directly.

• Speed control and speed PID tuning: If it is intended to control both speed and the torque, then the speed loopshould be closed as given in the block diagram of level 4. The reference speed adjusted by the user is compared tothe speed feedback and then the error is compensated by speed PID module which needs to be tuned at this level.The output of the speed PID is connected to another PID regulating Iq (stator current torque generatingcomponent), and the system increases or decreases the torque generation depending on the actual speed level vsspeed reference. For example, when the system is loaded, motor speed tends to reduce and the systemimmediately increase the torque generation to handle the applied load and indirectly keep the speed at thereference level. Once the speed PID is tuned at a certain operating point, the user needs to examine the robustnessof the speed loop under various torque/speed levels, step load or any other torque/speed profile applied to user’ssystem.

• Now, the actual rotor position is used: It was confirmed in build level 3 that position information (bothelectrical and mechanical) was correctly appearing at the outputs of the QEP drive module. In build level 4, thesimulated angle provided by RAMP_GEN is no longer needed. This can now be replaced by the actual measuredelectrical angle, theta_elec, which is used as angular position feedback for the Park and inverse Park transforms.

• Soft-switches helps to manage control loops: The latest incremental build levels are supported by loop switches(a software variable in the code, lsw) to manage the loops. For instance, when lsw=0, the rotor is locked to theinitial rotor position which is essential for sensored applications. Afterwards, the lsw is set to 1 to close thecurrent loops which help the motor start up smoothly. This is often needed for sensorless applications because thealgorithms need some time to converge to the actual position/speed value. Finally, lsw is set to 2 in order to closethe speed loop which let the customer control speed accurately and realize field orientation.

Figure 17. Build Level IV - Closed Speed Loop Test / FOC

TMS320C2000 Motor Control Primer 21

PI TuningPI tuning is often considered an art form, or perhaps magic.  Many customers use simulation tools to tune theircompensation systems. These have varying levels of success and are highly dependent on the accuracy of the plantmodel.  But we find the implementations from VisSim and Mathworks to be a good start.  For manual tuning, acommon procedure is offered in the documentation for the pid_grando module in controlSUITE's motor_libTuning the controllerDefault values for the controller coefficients are defined in the macro header file which apply unity gain through theproportional path, and disable both integral and derivative paths. A suggested general technique for tuning thecontroller is now described.Steps 1-4 are based on tuning a transient produced either by a step load change or a set-point step change.

Step 1.Ensure integral and derivative gains are set to zero. Ensure also the reference weighting coefficients (Kr &Km) are set to one.

Step 2.Gradually adjust proportional gain variable (Kp) while observing the step response to achieve optimum risetime and overshoot compromise.

Step 3.If necessary, gradually increase integral gain (Ki) to optimize the return of the steady state output to nominal.This will probably be accompanied by an increase in overshoot and oscillation, so it may be necessary to slightlydecrease the Kp term again to find the best balance.

TMS320C2000 Motor Control Primer 22

Step 4.If the transient response exhibits excessive oscillation, this can sometimes be reduced by applying a smallamount of derivative gain. To do this, first ensure the coefficients c1 & c2 are set to one and zero respectively. Next,slowly add a small amount of derivative gain (Kd). The controller will be very sensitive to this term and may becomeunstable so be sure to start with a very small number.Steps 5 & 6 only apply in the case of tuning a transient set-point. In the regulator case, or where the set-point is fixedand tuning is conducted against changing load conditions, they are not useful.

Step 5.Overshoot and oscillation following a set-point transient can sometimes be improved by lowering thereference weighting in the proportional path. To do this, gradually reduce the Kr term from its nominal unity value tooptimize the transient. Note that this will change the loop sensitivity to the input reference, so the steady statecondition will change unless integral gain is used.

Step 6.If derivative gain has been applied, transient response can often be improved by changing the referenceweighting, in the same way as step 6 except that in the derivative case steady state should not be affected. Slowlyreduce the Km variable from it’s nominal unity value to optimize overshoot and oscillation. Note that in many casesoptimal performance is achieved with a reference weight of zero in the derivative path, meaning that the differentialterm acts on purely the output, with no contribution from the input reference.The derivative path introduces a term which has a frequency dependent gain. At higher frequencies, this can causenoise amplification in the loop which may degrade servo performance. If this is the case, it is possible to filter thederivative term using a first order digital filter in the derivative path. Steps 7 & 8 describe the derivative filter.

Step 7.Select a filter roll-off frequency in radians/second. Use this in conjunction with the system sample period (T)to calculate the filter coefficients c1 & c2 (see equations 5 & 6).

Step 8.Note that the c1 coefficient will change the derivative path gain, so adjust the value of Kd to compensate forthe filter gain. Repeat steps 5 & 6 to optimize derivative path gain.

PU System Model and Base ValuesIn electrical engineering, a per-unit system is the expression of system quantities as fractions of a defined base unitquantity. Calculations are simplified because quantities expressed as per-unit (between -1 and +1) are the sameregardless of the voltage, current etc level. Advantages of using the pu system for motor control applications include:• Once the base values are initialized in the code, the code will handle the rest and the parameter dependency will

be minimized.• Migrating to a new custom design system will be as easy as modifying the base values.• For fixed point devices, pu system allows the user to reduce the amplitude of the variables in order to get a

fractional part with a maximum precision.Conversion of per-unit quantities to volts, ohms, or amperes requires knowledge of the base that the per-unitquantities were referenced to. In the TI DMC systems, the base values are selected as the maximum measurablequantity of the peak of phase voltage, current etc. by the ADC. This is directly related to the current and voltagesensing circuits and the voltage dividers used to down-scale the actual voltage or current quantities to ADC input

TMS320C2000 Motor Control Primer 23

voltage range, which is typically 3 to 3.3V. Later, the measured voltage by ADCs will be converted to put quantity inthe code. The calculation of the pu values can be formulated as:

The selection of the base quantities is relative and can be any appropriate value as long as it is consistent within thewhole system. For instance, assuming that the peak of the maximum measurable phase current is 20A on a DMC kit,the base current value can be selected as 20 where ±1pu represents ±20A in the code.

Similarly, the base voltage can be selected as the peak of maximum measurable phase voltage in the system.Assuming that the dc bus voltage is 400V, base voltage is selected as 400V/√3.

DMC Systems: Legacy VS controlSUITEThere are basically two separate TI DMC systems offering similar solutions for motor control with minordifferences. These differences can be summarized as:• controlSUITE supports Piccolo (2803x, fixed point) and Delfino (2833x, floating point) whereas Legacy supports

280x and 281x (both fixed point).• In controlSUITE the DMC Library modules are optimized macros whereas legacy modules are regular C

functions typically 2-3 times less efficient.• The recent TI DMC updates are announced through controlSUITE since 2010.• Legacy is motor control specific whereas controlSUITE is more comprehensive system covering almost all C2000

based applications.The DMC projects in the Legacy and ControlSUITE are given in the table below:http:/ / www. ti. com/ c2000dmc#dmc [6]

Table 4. Projects in controlSUITE and Legacy

TMS320C2000 Motor Control Primer 24

Motor Type Description Legacy controlSUITE

3-ph ACI Sensored – Tacho i/p Scalar Control / SVPWM 281x 280x 2803x

3-ph ACI Sensored – Tacho or Encoder Field Oriented Control / SVPWM 281x 280x 2803x

3-ph ACI Sensorless – Direct Flux Estimator Field Oriented Control / SVPWM 281x 280x 2803x 2833x

3-ph PMSM Sensored – Incremental Encoder Field Oriented Control / SVPWM 281x 280x 2803x

3-ph PMSM Sensorless – Sliding Mode Observer Field Oriented Control / SVPWM 281x 280x 2803x 2833x

3-ph PMSM Sensored – Incremental Encoder Position Control / SVPWM 281x 280x 2803x

3-ph PMSM Sensored – Resolver Field Oriented Control / SVPWM 281x 280x TBD

3-ph BLDC Sensored – Hall Effect Sensors Trapezoidal Control 281x 280x 2803x

3-ph BLDC Sensorless – BEMF Sensing Trapezoidal Control 281x 280x 2803x

3-ph BLDC Sensorless – Sinusoidal Control Field Oriented Control / SVPWM - 2803x

Brushed DC Sensored – QEP Position and speed control 281x 280x Q410

Stepper Motor Sensorless – Discrete Angle Est. Position and Speed Control 280x Q410

More About controlSUITEcontrolSUITE™ is the content and content management tool for C2000™ development. It includes a comprehensivesuite of software that significantly decreases development time and accommodates different experience levels andprogramming preferences. It is also a one-stop shop for everything needed for C2000 system development.controlSUITE’s main features include:• controlSUITE desktop graphical navigation tool• Manual or auto update, to insure synchronization with latest content• Devices: first-level device initialization, system tasking, and example projects• Libraries: foundational libraries and utilities for math, DSP, IQMath, CLA, floating point, flash, boot, and specific

applications• Kits: Entry level to application specific full voltage reference designs, including open tooled hardware, GUIs,

system guides, and CCStudio projects• Direct Links to: application notes, datasheets, user’s guides• Training: forums, videos, on-line, in-person, and self-paced workshops

Figure 18. controlSUITE Desktop Graphical Navigation Tools

TMS320C2000 Motor Control Primer 25

System Level DMC Documentation SupportIn addition to the DMC Library documents detailed in the previous sections, all C2000 motor control projects aresupported by a rich set of collateral to shorten the development time. These documents basically provide informationabout the motor type used in the project, control theory (e.g. FOC, trapezoidal control) system overview, hardwareconfiguration, incremental build levels, hardware components, GUI related documents etc.

Quickstart Guide and Graphical User Interface (GUI)In controlSUITE™, an open source graphical user interface is designed for sensorless HVDMC projects so that theusers can visually and quickly evaluate the DMC kit and software without having to learn and configure theunderlying project software or install CCS. Note that the GUI is not a development environment but intended fordemonstration purposes only. The GUI supports all three kinds of motors (ACI, PMSM, and BLDC). The HVDMCkit ships with both a Piccolo™ F28035 and a Delfino™ F28335 controlCARD. Only the F28035 card is pre-flashedwith the code that enables interface to this GUI. The flashed code is optimized for running sensorless FOC on ACIand PMSM motor and sensorless trapezoidal control on a BLDC motor that are available from the TI website. Notethat the performance of the motor with the flashed image is not a metric of quality of control and performance levelsachievable using the TI DMC library. The GUI allows the user to select the motor type, visually inspect somewaveforms (e.g., current, voltage, back-emf , etc.), numerically watch bus voltage, estimated speed, set the referencespeed, and change the graph update rate and graph scale. A snapshot of GUI is shown in Figure 19.

Figure 19. Graphical User Interface for Motor Control

TMS320C2000 Motor Control Primer 26

The GUI exe file, flash image, and related files can be found in Desktop -Kits -Folders -Example GUI, or at thedirect path of:

C:\ti\controlSUITE\development_kits\HVMotorCtrl+PfcKit_v1.3\~GUI

DMC System User GuidesThe system user guide is the most critical document explaining the system overview, applied theory, hardwareconfiguration, and incremental build levels. All motor control projects have a user's guide which includes:• Motor Types: In this section electromechanical structure of the motor used in the project is introduced briefly.

Synchronous / asynchronous operation, advantages of the particular motor type, the industrial areas where themotor type fits, etc., are briefly discussed.

• Control Theory: In this section the theory of the motor control is explained both verbally and mathematically.The philosophy behind the motor control type (e.g., FOC), benefits of the control type, typical applications,technical background, block diagrams and basic scheme are discussed in this section.

• System Overview: A brief summary of the DMC modules used in the project, some benchmark quantities likenumber of instruction cycles at the modular and system level, the size of the program, and data memory necessaryfor each project are given in this section. System features such as development environment, target controller,switching frequency, ISR source, used peripherals and mapping, system level drawings and software flow are alsogiven here.

• Hardware Configuration: In this section a list of check list is provided to the user to make sure that thehardware platform is ready to run. The list includes basic instruction regarding the jumper setting, supply, motor,and sensor connections, switch state, etc.

• Incremental Build Levels: As discussed in the previous sections, the DMC system is gradually built up in orderfor the final system can be confidently operated. A number of phases of the incremental system build are designedto verify the major software modules used in the system. The details of each level and related block diagrams aregiven in this section.

TMS320C2000 Motor Control Primer 27

These can be found in controlSUITE Desktop -Kits -Documentation or directly:C:\ti\controlSUITE\development_kits\HVMotorCtrl+PfcKit_v1.3\HVPM_Sensored\~Docs

Or for Legacy at:C:\tidcs\DMC\c28\v32x\sys\pmsm3_1_280x\doc

Hardware Guide and How to Run GuidesThe hardware guide describes the target kit contents and hardware details, and explains the functions and locationsof jumpers and connectors present on the board. This document supersedes all the documents available for the kit.The items discussed in this document include:• Kit content• Kit (electrical) features• Functionality of the each block on the board• Powering the board• Boot modes• GUI connection• Ground levels and safety• Hardware resource settings• Jumpers and connectors, etc.The “How to Run” guide explains the steps needed to run the target kit with the software supplied throughcontrolSUITE. The list of document content is given below:• Hardware configuration• Motor control experiment hardware setup instructions• Software setup for the kit projects• Set up Code Composer Studio• Configuring a project• Setup watch window and graphsBoth of the documents can be found in controlSUITE or directly:

C:\ti\controlSUITE\development_kits\HVMotorCtrl+PfcKit_v1.3\~Docs

Hardware Development PackageIn controlSUITE, a hardware development package is prepared for each hardware platform including:• Bill of materials• Schematics and layouts• Gerbers• Pin descriptions• Associated datasheetsThis package helps the users to build their own boards using TI design and layout. Found in controlSUITE Desktop-Kits -Folders or directly:

C:\ti\controlSUITE\development_kits\HVMotorCtrl+PfcKit_v1.3\~HVMotorCtrl+PFC-HWdevPkg

TMS320C2000 Motor Control Primer 28

Key CCS Features for DMC DevelopersCode Composer Studio (CCSudio) is the integrated development environment for TI’s micro-controllers andapplication processors. CCS includes a suite of tools used to develop and debug embedded applications. It includescompilers for each of TI's device families, source code editor, project build environment, real-time debugger,profiler, simulators and many other features. A link for a free download of CCSv4 is included in controlSUITEDesktop.

Figure 20. Code Composer Studio Interface

Software FlowAs mentioned, the DMC Systems are highly modular, allowing for re-use and re-targeting. The trade off is that themodularity can initially be confusing as instead of a single C file, there are many separate files and functions beingcalled. Let’s look at this by continuing to examine the High Voltage Kit Sensorless PMSM project. Explore thefolder through controlSUITE Desktop-Kits-Kit Folder or directly:

C:\ti\controlSUITE\development_kits\HVMotorCtrl+PfcKit_v1.3\HVPM_Sensorless

[PROJECT_NAME]-SETTINGS.HThis header file defines global settings for the project, including Incremental build level, system clock frequency,ISR frequency, and motor parameter settings.

[PROJECT_NAME]-DEVINIT_[F28XXX].CInitializes the device and the GPIO mux options (fixed function pins like ADC are already initialized by default).The DevInit file disables the watchdog timer, sets the clock/PLL, initializes the PIE, and then configures each GPIOto its own pin function. The DevInit file is target specific and is different based on the pin-out of the specific device.

TMS320C2000 Motor Control Primer 29

[PROJECT_NAME].HThis is the header file which lists all of the DMCLibrary components that will be used in the project. There is asection for the device independent MATH blocks as well as the device dependent DRIVERS. When creating yourown project you can directly use the MATH blocks as they exist in the DMCLib controlSUITE pathC:\ti\controlSUITE\libs\app_libs\motor_control\math_blocks but it is recommended that you place the DRIVERSinside your specific project as they will need to be customized to your specific implementation. For controlSUITEthe first DRIVER implementations were done for the High Voltage Kit, so those projects also point to thecontrolSUITE path, but you will notice for subsequent kits -like the Low Voltage versions -the drivers were broughtinto the specific project and modified as needed.These DRIVER blocks additionally use files located in the controlSUITE\device_supportorcontrolSUITE\development_kits\~SupportFiles for setting peripheral configuration.

[PROJECT_NAME].CLet’s examine the main source file for this project: HVPM_Sensorless.cThe first statements include five header files.1. PeripheralHeaderIncludes.h: LOCATION: C:\ti\controlSUITE\development_kits\~SupportFiles\F2803x_headers

PeripheralHeaderIncludes.h is a device specific header file that is chosen based on the include paths chosen inCCS. This header file is responsible for adding the correct set of F28xxx header files needed by the target anddefining several target specific constants.

2. IQmathLib.h: LOCATION: C:\ti\controlSUITE\libs\math\IQmathIQmathLib.h is the math library discussed inSection 2.1 of this document

3. HVPM_Sensorless.h:Discussed in Section 3.34. HVPM_Sensorless-Settings.h:Discussed in Section 3.35. math.h: LOCATION: C:\Program Files\Texas Instruments\ccsv4\tools\compiler\C2000 Code Generation Tools

5.2.7\include Math.h header file is the standard math and trigonometric functions supported by the CodeGeneration tools.

Lines 26 through 108:

Includes function definitions for system initialization, state machine initialization, and variable definitions.Lines 109 through 157:

Instance and define the project variable names for any of the DMCLib blocks that will be used in the project.We now enter into the main program execution which can be summarized as follows:Main1. Set-up three CPU timers for A, B, C state machine tasking

• Tasking could consist of• Communications – A program may need to transmit data externally via a peripheral such as the CAN, SPI,

or SCI• Variable Conversion/Scaling – Many variables used in a system are not completely obvious in what they

translate to in real world units. This may happen for many reasons including the 0-3V range of the ADC aswell as the way data is stored in various peripheral registers. The user may instead want to view thesevariables in real world units so that they can be sent externally to a data logger or so the program is easier touse.

• Project specific events such as updating coefficients or enabling/disabling an output2. Initialize DMCLib modules that require initialization3. ISR/PIE servicing

TMS320C2000 Motor Control Primer 30

4. Enter idle / background loop• A Tasks (@1ms)

• A1—Not used in this project• A2—Not used in this project• A3—Not used in this project

• B Tasks (@5ms)• B1—Toggle GPIO-00• B2—Not used in this project• B3—Not used in this project

• C Tasks (@50ms)• C1—Toggle GPIO-34• C2—Not used in this project• C3—Not used in this project

ISR (@ ISR frequency rate)1. Verify ISR Ticker2. If “BUILDLEVEL= X“ [setting in HVPWM_Sensorless-Settings.h] </nowiki>

• CONNECT together inputs/outputs of software blocks• CALL each macro function

3. Refresh Interrupt

Hardware ToolsTI currently offers two different hardware platforms for developing digital motor control applications, with severalmore planned. These tools provide a great way to learn and experiment with digital control of high and low voltagemotors and to use PFC to increase efficiency of operation.

High Voltage Motor Control and PFC Developer's KitThe High Voltage Motor Control and PFC Developer's Kit [7] provides an easy, open-source way to evaluate theC28x microcontrollers and TI analog in a high voltage environment. A single 28x MCU controls the power factorcorrection (PFC) stage and the motor control stage. The PFC takes a line level AC input (~110 to ~240VAC) andoutputs up to 750 watts of power, regulated by closed loop control. The motor driver stage can be driven from eitherthe PFC or from a separate power stage and accepts up to 350V and outputs up to 1.5 kilowatts of power. The motordriver stage can drive the three most common types of brushless motors, AC induction, brushless DC, and permanentmagnet synchronous motors. The kit has all the features to implement sensored and sensorless control of each motortype. The software and hardware for the kit is completely open source.The kit has the following key features:• 3-phase inverter stage

• 350V DC max input voltage• 1.5 kW maximum load• QEP and CAP inputs available for speed and position measurement• Hall sensor input available for trapezoidal control• Sensorless and sensored field-oriented control of ACI motor• Sensorless and sensored field-oriented control of PMSM motor• Sensorless and sensored trapezoidal control of BLDC motor• Sensorless and sensored sinusoidal control of BLDC motor

TMS320C2000 Motor Control Primer 31

• Miscellaneous• Four channel PWM DAC channels to observe the system variables on an oscilloscope to enable easy debug of

control algorithms• Isolated CAN interface for communication over CAN bus• Onboard Isolated JTAG emulation• Isolated UART through the SCI peripheral and the FTDI chip

The Hardware Developer’s Package is available and includes schematics, bill of materials, Gerber files, etc.Figure 21. High Voltage DMC Board

Figure 22. High Voltage DMC Board Block Diagram

TMS320C2000 Motor Control Primer 32

Low Voltage Motor Control and PFC Developer's KitThe Low Voltage Motor Control and PFC Developer's Kit provides a safe way to learn and experiment with digitalcontrol of low voltage motors and the use of PFC to increase efficiency of operation. The kit provides direct accessto all of the enhancements and features of the 28x architecture, and also enables developers to determine quickly theprocessing resources required to implement basic motor control. From this baseline, they are then able to bring inadvanced algorithms to trade off the remaining processing capacity for greater accuracy, better performance, higherpower efficiency, control of multiple motors, and a various other options. In this way, developers can architectsystems specifically optimized for their application constraints and requirements.The low voltage kit has the following key features:• 3-Phase Inverter Stages (DRV8402)

• 24-36Vdc input (kit includes 24V motors and a 24V power supply)• 40W output from each inverter stage• 10KHz switching frequency per inverter stage (default)• High precision low-side sensing using the C2000’s high performance ADC and Texas Instruments' OPA2350

high-speed op-amps• QEP and CAP inputs available on board for speed and position measurement• Sensorless control of two PMSM motors

• Power Factor Correction Stage• Two-phase interleaved topology• 13-16Vac input provides 24Vdc the DCBus• Approximately 90% efficiency• 80W output continuous (40W without forced air flow through heatsink)• 100KHz switching frequency (200kHz effective when both phases are operating)• 50KHz PFC control loop frequency• Capable of phase shedding

• Miscellaneous• On-board isolated JTAG emulation• Over-current and over-voltage protection for the PFC stage and over-current protection for each rectifier

section• UART communication header available for host control• Hardware Developer’s Package is available and includes schematics, bill of materials, Gerber files, etc.• Two channel PWM DAC channels to observe the system variables on an oscilloscope to enable easy debug of

control algorithmsFigure 23. Low Voltage DMC Board

TMS320C2000 Motor Control Primer 33

Figure 24. Low Voltage DMC Board Block Diagram

TMS320C2000 Motor Control Primer 34

Low Voltage Three Phase BLDC/PMSM Kits (DRV83x + MCUcontrolCARD)DRV8312-C2-KIT [8] & Upcoming DRV8332-C2-KITShips with controlCARD (C2 = C2000 Piccolo F28035), demonstrates BLDC Trapezoidal (Sensored and Sensorless)and Sensorless FOC.Kits include Isolated USB-JTAG, Isolated UART, Isolated SPI, and Isolated CAN.All documenation, source, GUIs, BOM, Gerbers, etc. available through www.ti.com/controlsuiteUpcoming DRV8301HC-C2-KIT (60A FETs)Ships with controlCARD (C2 = C2000 Piccolo F28035), demonstrates new Sensorless Trapezoidal Control andSensorless FOC.

References[1] http:/ / focus. ti. com/ docs/ toolsw/ folders/ print/ sprc080. html[2] http:/ / focus. ti. com/ docs/ toolsw/ folders/ print/ sprc215. html[3] http:/ / www. ti. com/ controlsuite[4] http:/ / www. ti. com/ c2000dmc[5] http:/ / www. ti. com/ lit/ pdf/ spraak2[6] http:/ / www. ti. com/ c2000dmc#dmc[7] http:/ / focus. ti. com/ docs/ toolsw/ folders/ print/ tmdshvmtrpfckit. html[8] http:/ / focus. ti. com/ docs/ toolsw/ folders/ print/ drv8312-c2-kit. html

Article Sources and Contributors 35

Article Sources and ContributorsTMS320C2000 Motor Control Primer  Source: http://processors.wiki.ti.com/index.php?oldid=70247  Contributors: A0323029, ChrisClearman, Lheustess, Twolff

Image Sources, Licenses and ContributorsImage:32bit_number_prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:32bit_number_prugi6.gif  License: unknown  Contributors: TwolffImage:fraction_number_prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Fraction_number_prugi6.gif  License: unknown  Contributors: TwolffImage:ACI Sensored FOC System BD.gif  Source: http://processors.wiki.ti.com/index.php?title=File:ACI_Sensored_FOC_System_BD.gif  License: unknown  Contributors: TwolffImage:ACI_Sensored_FOC_System_BD_1to1_Mapping.gif  Source: http://processors.wiki.ti.com/index.php?title=File:ACI_Sensored_FOC_System_BD_1to1_Mapping.gif  License:unknown  Contributors: TwolffImage:Target_and_Application_Ind_Modules.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Target_and_Application_Ind_Modules.gif  License: unknown  Contributors:TwolffImage:Target_Ind_App_Config_Modules.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Target_Ind_App_Config_Modules.gif  License: unknown  Contributors: TwolffImage:Target_Dep_Drive_Modules.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Target_Dep_Drive_Modules.gif  License: unknown  Contributors: TwolffImage:Utility_Debug_Modules.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Utility_Debug_Modules.gif  License: unknown  Contributors: TwolffImage:Testing_Evaluating_Modules.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Testing_Evaluating_Modules.gif  License: unknown  Contributors: TwolffImage:Library_Docs_Location_controlSUITE.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Library_Docs_Location_controlSUITE.gif  License: unknown  Contributors:TwolffImage:Snapshot_Typ_Target_Ind_Module.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Snapshot_Typ_Target_Ind_Module.gif  License: unknown  Contributors: TwolffImage:Snapshot_1st_C_Interface_Sect.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Snapshot_1st_C_Interface_Sect.gif  License: unknown  Contributors: TwolffImage:snapshot_theo_backgr_sec_prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Snapshot_theo_backgr_sec_prugi6.gif  License: unknown  Contributors: TwolffImage:Typical_Mod_Declaration_Macro_Def.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Typical_Mod_Declaration_Macro_Def.gif  License: unknown  Contributors:TwolffImage:Build_1_Check_Vital_Signs.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Build_1_Check_Vital_Signs.gif  License: unknown  Contributors: TwolffImage:Build_2_Invrtr_Test_ADC_Calibrate.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Build_2_Invrtr_Test_ADC_Calibrate.gif  License: unknown  Contributors: TwolffImage:Build_3_Closed_Current_Loop_Test.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Build_3_Closed_Current_Loop_Test.gif  License: unknown  Contributors: TwolffImage:Build_4_Closed_Speed_Loop_Test_FOC.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Build_4_Closed_Speed_Loop_Test_FOC.gif  License: unknown  Contributors:TwolffImage:Equation.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Equation.gif  License: unknown  Contributors: TwolffImage:Example code prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Example_code_prugi6.gif  License: unknown  Contributors: TwolffImage:controlSUITE_Navigation_Tools.gif  Source: http://processors.wiki.ti.com/index.php?title=File:ControlSUITE_Navigation_Tools.gif  License: unknown  Contributors: TwolffImage:GUI_Motor_Control.gif  Source: http://processors.wiki.ti.com/index.php?title=File:GUI_Motor_Control.gif  License: unknown  Contributors: TwolffImage:Code_Composer_Studio_Interface-1.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Code_Composer_Studio_Interface-1.gif  License: unknown  Contributors: TwolffImage:High Voltage DMC Board.gif  Source: http://processors.wiki.ti.com/index.php?title=File:High_Voltage_DMC_Board.gif  License: unknown  Contributors: TwolffImage:High voltage dmc bbc prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:High_voltage_dmc_bbc_prugi6.gif  License: unknown  Contributors: TwolffImage:Low voltage dmc board prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Low_voltage_dmc_board_prugi6.gif  License: unknown  Contributors: TwolffImage:Low voltage dmc bbd prugi6.gif  Source: http://processors.wiki.ti.com/index.php?title=File:Low_voltage_dmc_bbd_prugi6.gif  License: unknown  Contributors: Twolff

LicenseTHE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHERAPPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BEA CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.License1. Definitionsa. "Adaptation" means a work based upon the Work, or upon the Work and other pre-existing works, such as a translation, adaptation, derivative work, arrangement of music or other alterations of a literary or artistic work, or

phonogram or performance and includes cinematographic adaptations or any other form in which the Work may be recast, transformed, or adapted including in any form recognizably derived from the original, except that a workthat constitutes a Collection will not be considered an Adaptation for the purpose of this License. For the avoidance of doubt, where the Work is a musical work, performance or phonogram, the synchronization of the Work intimed-relation with a moving image ("synching") will be considered an Adaptation for the purpose of this License.

b. "Collection" means a collection of literary or artistic works, such as encyclopedias and anthologies, or performances, phonograms or broadcasts, or other works or subject matter other than works listed in Section 1(f) below,which, by reason of the selection and arrangement of their contents, constitute intellectual creations, in which the Work is included in its entirety in unmodified form along with one or more other contributions, each constitutingseparate and independent works in themselves, which together are assembled into a collective whole. A work that constitutes a Collection will not be considered an Adaptation (as defined below) for the purposes of this License.

c. "Creative Commons Compatible License" means a license that is listed at http:/ / creativecommons. org/ compatiblelicenses that has been approved by Creative Commons as being essentially equivalent to this License,including, at a minimum, because that license: (i) contains terms that have the same purpose, meaning and effect as the License Elements of this License; and, (ii) explicitly permits the relicensing of adaptations of works madeavailable under that license under this License or a Creative Commons jurisdiction license with the same License Elements as this License.

d. "Distribute" means to make available to the public the original and copies of the Work or Adaptation, as appropriate, through sale or other transfer of ownership.e. "License Elements" means the following high-level license attributes as selected by Licensor and indicated in the title of this License: Attribution, ShareAlike.f. "Licensor" means the individual, individuals, entity or entities that offer(s) the Work under the terms of this License.g. "Original Author" means, in the case of a literary or artistic work, the individual, individuals, entity or entities who created the Work or if no individual or entity can be identified, the publisher; and in addition (i) in the case of a

performance the actors, singers, musicians, dancers, and other persons who act, sing, deliver, declaim, play in, interpret or otherwise perform literary or artistic works or expressions of folklore; (ii) in the case of a phonogram theproducer being the person or legal entity who first fixes the sounds of a performance or other sounds; and, (iii) in the case of broadcasts, the organization that transmits the broadcast.

h. "Work" means the literary and/or artistic work offered under the terms of this License including without limitation any production in the literary, scientific and artistic domain, whatever may be the mode or form of its expressionincluding digital form, such as a book, pamphlet and other writing; a lecture, address, sermon or other work of the same nature; a dramatic or dramatico-musical work; a choreographic work or entertainment in dumb show; amusical composition with or without words; a cinematographic work to which are assimilated works expressed by a process analogous to cinematography; a work of drawing, painting, architecture, sculpture, engraving orlithography; a photographic work to which are assimilated works expressed by a process analogous to photography; a work of applied art; an illustration, map, plan, sketch or three-dimensional work relative to geography,topography, architecture or science; a performance; a broadcast; a phonogram; a compilation of data to the extent it is protected as a copyrightable work; or a work performed by a variety or circus performer to the extent it is nototherwise considered a literary or artistic work.

i. "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exerciserights under this License despite a previous violation.

j. "Publicly Perform" means to perform public recitations of the Work and to communicate to the public those public recitations, by any means or process, including by wire or wireless means or public digital performances; tomake available to the public Works in such a way that members of the public may access these Works from a place and at a place individually chosen by them; to perform the Work to the public by any means or process and thecommunication to the public of the performances of the Work, including by public digital performance; to broadcast and rebroadcast the Work by any means including signs, sounds or images.

k. "Reproduce" means to make copies of the Work by any means including without limitation by sound or visual recordings and the right of fixation and reproducing fixations of the Work, including storage of a protectedperformance or phonogram in digital form or other electronic medium.

2. Fair Dealing RightsNothing in this License is intended to reduce, limit, or restrict any uses free from copyright or rights arising from limitations or exceptions that are provided for in connection with the copyright protection under copyright law or otherapplicable laws.3. License GrantSubject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as statedbelow:a. to Reproduce the Work, to incorporate the Work into one or more Collections, and to Reproduce the Work as incorporated in the Collections;b. to create and Reproduce Adaptations provided that any such Adaptation, including any translation in any medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made to the original

Work. For example, a translation could be marked "The original work was translated from English to Spanish," or a modification could indicate "The original work has been modified.";c. to Distribute and Publicly Perform the Work including as incorporated in Collections; and,d. to Distribute and Publicly Perform Adaptations.e. For the avoidance of doubt:

License 36

i. Non-waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme cannot be waived, the Licensor reserves the exclusive rightto collect such royalties for any exercise by You of the rights granted under this License;

ii. Waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme can be waived, the Licensor waives the exclusive right to collectsuch royalties for any exercise by You of the rights granted under this License; and,

iii. Voluntary License Schemes. The Licensor waives the right to collect royalties, whether individually or, in the event that the Licensor is a member of a collecting society that administers voluntary licensing schemes, viathat society, from any exercise by You of the rights granted under this License.

The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media andformats. Subject to Section 8(f), all rights not expressly granted by Licensor are hereby reserved.4. RestrictionsThe license granted in Section 3 above is expressly made subject to and limited by the following restrictions:a. You may Distribute or Publicly Perform the Work only under the terms of this License. You must include a copy of, or the Uniform Resource Identifier (URI) for, this License with every copy of the Work You Distribute or

Publicly Perform. You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of the recipient of the Work to exercise the rights granted to that recipient under the terms of the License.You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties with every copy of the Work You Distribute or Publicly Perform. When You Distribute or PubliclyPerform the Work, You may not impose any effective technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License.This Section 4(a) applies to the Work as incorporated in a Collection, but this does not require the Collection apart from the Work itself to be made subject to the terms of this License. If You create a Collection, upon notice fromany Licensor You must, to the extent practicable, remove from the Collection any credit as required by Section 4(c), as requested. If You create an Adaptation, upon notice from any Licensor You must, to the extent practicable,remove from the Adaptation any credit as required by Section 4(c), as requested.

b. You may Distribute or Publicly Perform an Adaptation only under the terms of: (i) this License; (ii) a later version of this License with the same License Elements as this License; (iii) a Creative Commons jurisdiction license(either this or a later license version) that contains the same License Elements as this License (e.g., Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible License. If you license the Adaptation under one of thelicenses mentioned in (iv), you must comply with the terms of that license. If you license the Adaptation under the terms of any of the licenses mentioned in (i), (ii) or (iii) (the "Applicable License"), you must comply with theterms of the Applicable License generally and the following provisions: (I) You must include a copy of, or the URI for, the Applicable License with every copy of each Adaptation You Distribute or Publicly Perform; (II) Youmay not offer or impose any terms on the Adaptation that restrict the terms of the Applicable License or the ability of the recipient of the Adaptation to exercise the rights granted to that recipient under the terms of the ApplicableLicense; (III) You must keep intact all notices that refer to the Applicable License and to the disclaimer of warranties with every copy of the Work as included in the Adaptation You Distribute or Publicly Perform; (IV) whenYou Distribute or Publicly Perform the Adaptation, You may not impose any effective technological measures on the Adaptation that restrict the ability of a recipient of the Adaptation from You to exercise the rights granted tothat recipient under the terms of the Applicable License. This Section 4(b) applies to the Adaptation as incorporated in a Collection, but this does not require the Collection apart from the Adaptation itself to be made subject tothe terms of the Applicable License.

c. If You Distribute, or Publicly Perform the Work or any Adaptations or Collections, You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to themedium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or if the Original Author and/or Licensor designate another party or parties (e.g., a sponsor institute,publishing entity, journal) for attribution ("Attribution Parties") in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; (ii) the title of the Work if supplied; (iii) to theextent reasonably practicable, the URI, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and (iv) , consistent withSsection 3(b), in the case of an Adaptation, a credit identifying the use of the Work in the Adaptation (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Thecredit required by this Section 4(c) may be implemented in any reasonable manner; provided, however, that in the case of a Adaptation or Collection, at a minimum such credit will appear, if a credit for all contributing authors ofthe Adaptation or Collection appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by thisSection for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by theOriginal Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties.

d. Except as otherwise agreed in writing by the Licensor or as may be otherwise permitted by applicable law, if You Reproduce, Distribute or Publicly Perform the Work either by itself or as part of any Adaptations or Collections,You must not distort, mutilate, modify or take other derogatory action in relation to the Work which would be prejudicial to the Original Author's honor or reputation. Licensor agrees that in those jurisdictions (e.g. Japan), inwhich any exercise of the right granted in Section 3(b) of this License (the right to make Adaptations) would be deemed to be a distortion, mutilation, modification or other derogatory action prejudicial to the Original Author'shonor and reputation, the Licensor will waive or not assert, as appropriate, this Section, to the fullest extent permitted by the applicable national law, to enable You to reasonably exercise Your right under Section 3(b) of thisLicense (right to make Adaptations) but not otherwise.

5. Representations, Warranties and DisclaimerUNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNINGTHE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE,NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOTALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.6. Limitation on LiabilityEXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVEOR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.7. Terminationa. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Adaptations or Collections from You under this License,

however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different

license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of thisLicense), and this License will continue in full force and effect unless terminated as stated above.

8. Miscellaneousa. Each time You Distribute or Publicly Perform the Work or a Collection, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.b. Each time You Distribute or Publicly Perform an Adaptation, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this

agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not

be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.f. The rights granted under, and the subject matter referenced, in this License were drafted utilizing the terminology of the Berne Convention for the Protection of Literary and Artistic Works (as amended on September 28, 1979),

the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and the Universal Copyright Convention (as revised on July 24, 1971). These rights and subjectmatter take effect in the relevant jurisdiction in which the License terms are sought to be enforced according to the corresponding provisions of the implementation of those treaty provisions in the applicable national law. If thestandard suite of rights granted under applicable copyright law includes additional rights not granted under this License, such additional rights are deemed to be included in the License; this License is not intended to restrict thelicense of any rights under applicable law.