plus+1® guide create compiled code packages user manual

powersolutions.danfoss.com

MAKING MODERN LIVING POSSIBLE

User Manual

PLUS+1 GUIDECreate Compiled Code Packages

Front cover illustration: Greyscaled PLUS cover

User Manual PLUS+1 GUIDE, Create Compiled Code Packages

11078985 • Rev CA • Mar 20142

ContentsContents ....................................................................................................................................................................................... 2Risk ReductionRisk Reduction ............................................................................................................................................................................ 4Overview and RequirementsThe CCP Explained .................................................................................................................................................................... 5Creator Expectations ................................................................................................................................................................ 5The Illustrated CCP ProcessCCP Implementation Illustration ......................................................................................................................................... 6Learning about the CCPBasic Lessons ............................................................................................................................................................................... 7

Getting ready ........................................................................................................................................................................ 7Determining Functionality............................................................................................................................................... 7

Lesson 1: Creating an Interface Between CCP and GUIDENavigating the CCP Interface .......................................................................................................................................... 8Compile with RatatoskT3.................................................................................................................................................. 8C-code Modification Process .........................................................................................................................................10Compile with C-compiler ...............................................................................................................................................10Archive with your C-compiler .......................................................................................................................................10Packaging the CCP ............................................................................................................................................................10

Lesson 2: Create a GUIDE ProjectCreate a GUIDE project ....................................................................................................................................................11Download the GUIDE project .......................................................................................................................................14

HWD Interface TypesDatatypes ...................................................................................................................................................................................15HWD .............................................................................................................................................................................................15HWD-specific header files for basic GUIDE types. ......................................................................................................16Ratatosk T3 Interface TypesRatatoskT3 .................................................................................................................................................................................17Basic Ratatosk T3 Usage ........................................................................................................................................................17CCP TutorialBasic Tutorial Set Up ...............................................................................................................................................................18Tutorial References .................................................................................................................................................................19

Step 1: Adding functionality .........................................................................................................................................19Step 2: Precision .................................................................................................................................................................20Step 3: User Controlled Default Scale ........................................................................................................................22Step 4: Enabling Universal Conversions ....................................................................................................................27Step 5: Documentation ...................................................................................................................................................35

IDL Syntax The IDL Format .........................................................................................................................................................................38Character Sets ...........................................................................................................................................................................38Basic Character Groups .........................................................................................................................................................38Specific Character Groups ....................................................................................................................................................38Element Types...........................................................................................................................................................................39Interface Element ....................................................................................................................................................................39Top Element ..............................................................................................................................................................................39

#xclass Properties ..............................................................................................................................................................40#xclass elements ................................................................................................................................................................40Variable Formats ................................................................................................................................................................41Verbatim Formats ..............................................................................................................................................................41

Methods ......................................................................................................................................................................................42Init value .....................................................................................................................................................................................42

Method Variables ..............................................................................................................................................................43Method Verbatim Text .....................................................................................................................................................44

Contents


11078985 • Rev CA • Mar 2014 3

IDL Change LogChange Log ..............................................................................................................................................................................45003A versus 002A ...................................................................................................................................................................45004A versus 003A ...................................................................................................................................................................47RatatoskT3 Version 6.0CCP Macros ...............................................................................................................................................................................53TroubleshootingTroubleshooting ......................................................................................................................................................................55Quick FactsQuick Facts .................................................................................................................................................................................56Index

Revision HistoryRevision Date Comments

BA Dec 2010 Complete revision

BD Mar 2011 Fine tuning

BE Aug 2012 Tables added

BF April 2013 Updated for functionalities

CA Mar 2014 New layout

Revision History

Contents


11078985 • Rev CA • Mar 20144

Risk Reduction WWarningIt is the responsibility of the Compiled Code Package creator to ensure that the Compiled Code Package is safe to use. RatatoskT3 helps to ensure that inputs and outputs are buffered, but the ultimate responsibility is on the developer of each Compiled Code Package. Using an untested compiled code package (CCP) in an application can produce an application that is unstable and unpredictable. An unstable application can cause unexpected machine movements, resulting in injury and equipment damage. • To reduce risks in using an application that contains a CCP, the creator of the CCP must make certain that the CCP complies with the following criteria: • The code works on the target platform in all eventualities. • The compiler, compiler version and compiler flags that are defined in this document are used. • All rules and guidelines for creating Compiled Code Packages have been followed • Code is written in a way such that it does not interfere with the PLUS+1 GUIDE data flow. I.e. functions will return in a timely manner and potentially blocking calls and loops that do not have a fixed maximum number of iterations are not used. • The code is designed in a way such that it uses as little stack memory as possible. The stack usage is also predictable. For example; recursion is not used. • Kernel functions or other resources in the kernel are not used, unless the corresponding HWD documentation explicitly allows it by providing a well defined API intended for this specific purpose. • The code in the Compiled Code Packages does not in any way assume to know how PLUS+1 GUIDE code generation works, and/or relies on this never changing (Exception: Any part of the code generation that might be described in this document). • A User Manual is provided for the CCP describing the API interface and functionality of the CCP. • • Integration tests that are required to be performed by the graphical developer are defined. For example how to use maximum stack space in the CCP so stack overflow for the complete application can be tested. • Data passed between application and CCP use only the interface defined by the IDL file.


11078985 • Rev CA • Mar 2014 5

The Compiled Code Package (CCP) is a feature in PLUS+1 GUIDE that allows users to use other code than the standard graphical PLUS+1 GUIDE code.

As long as the code has a format that can be linked with the compiler used for the target platform (Platform = Hardware + Compiler + Compiler Version), any code can be used. In practice because of the existing compilers for the PLUS+1 hardware, Assembler, C-code and in some cases C++-code can be used. CCP requires the code to be compiled and put into a library format before the CCP is created.

If the user wants to re-use existing code or develop new code, Danfoss provides RatatoskT3.exe, a tool that is used to create the “glue” between existing C-code and the interface needed for the PLUS+1 GUIDE graphical code. The tool is delivered in the PLUS+1 GUIDE installation.

It is recommended to first read the information in the PLUS+1 GUIDE manual about how CCP is used in GUIDE; (“How to Add a Compiled Code Package”) and the description of the components (“Create Externally Defined Class” and “Call Method of Externally Defined Class”).

The CCP Explained

It is important to understand the difference in roles between the user and the creator of the CCP.

y The creator of a CCP is expected to have a software developer background and have experience with the programming language used.

y The creator must take the responsibility to verify and document the CCP. y It is expected that the creator de-bug the source code before the PLUS+1 GUIDE interface is

created. y It is expected that the creator also verifies the complete CCP in a PLUS+1 GUIDE test application. y The creator is expected to have read both this manual and the PLUS+1 GUIDE manual.

It is important that the CCP creator is aware that the skill level of the CCP user will vary. The user cannot change and/or correct a compiled CCP. The user is not expected to have read this document, only the PLUS+1 GUIDE manual. The only reqirement of a CCP user is to be able to use it as a fully tested, debugged and documented building block in his graphical application. The creator must provide adequate documentation for the user to use the CCP. A document explaining the API would be considered a minimum requirement.

Overview and Requirements

Creator Expectations

Zip File

Step 5Create Zip File

Lib file

Implementation OBJ File

Interface OBJ File

Step 3Compile InterfaceC Code

Process IDL File

to create Interface

C Code

Step 4Create LibFile

Step 1Compile

implementation C Code

Common Implementation/Interface type definitions H file.

All names and definitions should be globally unique,

including H file name.

OPTIONALPr

epar

atio

n

Interface C & H Files

Cre

ate

CCP

Star

tC

reat

e CC

P En

dRe

sult

Step 2

ImplementationC & H Files

InterfaceIDL File

OPTIONAL

CCP Help FilesTXT, PDF, HTML, CHM

HWD SpecificGUIDE Type

Definition H File

Result Files

Optional Files

Process Step

Temporary Files

Mandatory Files

KEY


11078985 • Rev CA • Mar 20146

The Illustrated CCP Process

CCP Implementation Illustration


11078985 • Rev CA • Mar 2014 7

This section contains two basic lessons to help you learn about the CCP functionality. For this exercise we will use a PLUS+1 Microcontroller.

These two lessons will help you to understand: y How to start up, compile, and create a small CCP. y How to create a PLUS+1 application that uses the CCP.

To complete these lessons, you will need the following: y A fully functional version of the PLUS+1 GUIDE 5.10 program or later installed on your PC. y A PLUS+1 HWD for the hardware you want to use. The HWD must support CCP and TI compiler

version 5.2.5. y Basic knowledge in how to use the PLUS+1 GUIDE and Service Tool. y An environment (TI compiler version 5.2.5 / TI Code Composer Studio) that allows you to compile

and archive for the hardware chosen.

Decide which functionality the CCP will enable.In this lesson you will create a function to convert from Fahrenheit to Celsius by creating an interface between CCP and GUIDE.

Learning about the CCP

Basic Lessons

Getting ready

Determining Functionality


11078985 • Rev CA • Mar 20148

Navigating the CCP Interface The first line is the header of the interface description.

The first field of the header CCP_TI_v525 is the Interface type. It shall have the same value as defined by the HWD of the target hardware that it is designed for. Refer to HWD-specific header files on page 16 of this document for a list of possible interface types.

The next field, Conversion, is the name of the CCP that will be visible for the user in GUIDE. It will also become the name of generated files such as C and H files. The idl-file itself must have this name and, as mentioned above, the extension “idl”.

The last field, 002A, is the current version of the interface definition language IDL. Use IDL version 002A for CCP development.

Inside the interface definition there is a class definition. It always starts with the keyword #xclass followed by the name of the class; in this case the name will be Conversion.

Inside the class definition there is a method defined. The method is the actual function of this CCP. It has a return data type S32 and a method name Celsius . After that in brackets comes an argument list with the argument fahrenheit of the data type S32. Refer to the sub chapter Datatypes on page 15 of this document for a list of possible data types.

From the interface definition, a c-file and an h-file is generated with the help of the tool RatatoskT3. The generated files contain a code skeleton in the programming language C for the defined CCP.

Locate RatatoskT3.exe in your GUIDE installation. The default installation path for English language Windows XP is for example: c:\Program Files\Danfoss\PLUS1\5.10\ P1Tools\P1Compiler\RatatoskT3.exe

Make sure that the working directory is where you have your idl file, then run the following command:

“[Your Ratatosk Installation Path]\RatatoskT3.exe“ input=Conversion.idl, c=yes, h=yes, silent=yes”

Output files: “Conversion.h” and “Conversion.c”.

Compile with RatatoskT3

The interface between CCP and GUIDE is described by a file with the extension “idl”. Create a file called “Conversion.idl” with the following contents:

CCP_TI_v525 Conversion 002A{ #xclass Conversion { S32 Celsius(S32 fahrenheit) { } }}

Lesson 1: Creating an Interface Between CCP and GUIDE


11078985 • Rev CA • Mar 2014 9

The generated c-file will have the following content://FILE: Conversion.c//IDL Type: CCP_TI_v525//IDL Name: Conversion//IDL Version: 002A//IDL CheckSum: 1C72//This file is automatically generated by RatatoskT3, //so change it only if you know what you are doing...

#include "./Conversion.h"

//XCLASS methods:

//XCLASS Conversion

//shared data (Do not use directly, use "SELF->SHARED" instead):Conversion_1C72_SHARED_TYPE Conversion_1C72_SHARED_INSTANCE;

S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit){ /*returnable variable, which _COULD_ be used for returning a value.*/ /* A value _MUST_ be returned from this function*/ S32 RESULT = 0;

/*in-data, which _SHOULD_ be read:*/ //fahrenheit;

return RESULT;}

//Variables:

//Functions:

“Conversion.c” is to be modified in the next step.

Compile with RatatoskT3



11078985 • Rev CA • Mar 201410

1. Remove all comments from Conversion.c (optional ):

#include "./Conversion.h"Conversion_1C5B_SHARED_TYPE Conversion_1C5B_SHARED_INSTANCE;S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit){ S32 RESULT = 0; return RESULT;}

2. Modify the function Conversion_Celsius to return the value of the conversion formula:

#include "./Conversion.h"Conversion_1C5B_SHARED_TYPE Conversion_1C5B_SHARED_INSTANCE;S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit){ return (fahrenheit - 32) * 5 / 9;}

3. The last thing needed to make this compile is to add definitions for the basic GUIDE data types. This is done by adding an HWD specific header file. Refer to the HWD-specific header files on page 16 of this manual for a list of possible header files.

In this case named CCP_TI_v525.h:

#include "./CCP_TI_v525.h"#include "./Conversion.h"Conversion_1C5B_SHARED_TYPE Conversion_1C5B_SHARED_INSTANCE;S32 Conversion_Celsius (Conversion * SELF, S32 fahrenheit){ return (fahrenheit - 32) * 5 / 9;}

Note 1: If you run RatatoskT3 again it will overwrite the C files you have edited.

Note 2: “Conversion_1C5B_SHARED_TYPE” will probably not be the exact name used in your code. It is important that this name is never changed manually, but that the name generated by RatatoskT3 is always used.

CL2000 Conversion.c -d”CCP_TI_v525” -pm -me -o3 -q -g -pdr -pdv -pden -pdse225 -pds303 -d"LARGE_MODEL" -ml -v28 -i”[Include Directory]”

C-code Modification Process

Archive with your C-compiler AR2000 –r Conversion.lib Conversion.obj

Compile with C-compiler

Packaging the CCP Using a standard ZIP-program, archive the library file and the IDL-file into a file named Conversion.zip.


CL2000 Conversion.c -d”CCP_TI_v525” -pm -me -o3 -q -g -pdr -pdv -pden -pdse225 -pds303 -d”LARGE_MODEL” -ml -v28 -i”[Include Directory]”


11078985 • Rev CA • Mar 2014 11

Create a new GUIDE project; use the HWD applicable for the hardware used in above steps to create a CCP.

Add your CCP to the project in the project manager (right click the application name and select “Add Compiled Code Package” in the pop-up menu).

Create a GUIDE project

Lesson 2: Create a GUIDE Project


11078985 • Rev CA • Mar 201412

Also use the following components;

4× Constant True4× Multi-character Typed Constant4× Simple Checkpoint

Connect the following Fahrenheit temperatures to each of the Method calls respectively: {-40, 0, 32 and 212}.

These values correspond to the Celsius temperatures: {-40, -18, 0 and 100}.

Connect Checkpoints to verify that this is indeed the output of the method.

Note that all names are case sensitive, and all types must match exactly what is specified in the idl file.

Create a GUIDE project Use the following components (from Connection in the Component Tab);

1× Create Externally Defined Class 4× Call Method of Externally Defined Class



11078985 • Rev CA • Mar 2014 13

Compile.

Create a GUIDE project



11078985 • Rev CA • Mar 201414

Connect the Hardware to the Service Tool and download the application. Log the created checkpoints, the result shall be as described below.

It looks good, except for the conversion from 0 Fahrenheit. The result is -17 when it should have been -18. The reason for this is a rounding error caused by working with integers. This problem will be addressed in a later tutorial in this manual.

Download the GUIDE project



11078985 • Rev CA • Mar 2014 15

The following data types can be used in the interface between the PLUS+1 GUIDE graphical code and the CCP code:

An HWD that supports Compiled Code Package (CCP) shall state this and also indicate which IDL TYPE to use in the API specification document.

Specific details about how to handle the Compiled Code Package in different HWD families is only described in this document and not in individual HWD documents.

Datatypes

Table 2: IDL Types for Different Platforms

Architecture Devices IDL Type Compiler Version

Command(see table 3,

line:

Archive Command

(see table 3, line:

H File(see table:

TI MCXX-XX CCP_TI_v525 5.25 1 2 4

ARM DP200/DP210 CCP_ARM_THUMB_v4 10

4.10 3 4 5

ARM DP250 CCP_ARM_v410 4.10 5 6 6

ARM SCXXX-XXX CCP_STM32FX0X441

2009q3-68 7 8 7

HWD

Table 1: Data Types and Ranges

Data Type Range Description

BOOL True or False False is equal to zero.True is everything not equal to zero.

U8 0—255 Unsigned 8 bits

S8 -128—127 Signed 8 bits

U16 0—65535 Unsigned 16 bits

U32 0—4294967295 Unsigned 32 bits

S32 -2147483648—2147483647 Signed 32 bit

All CCPs must use .LIB files to contain the object code.

Table 3: Compile/Archive Commands

1 CL2000 [IDL-Name].c -d”CCP_TI_v525” -pm -me -o3 -q -g -pdr -pdv -pden -pdse225 -pds303 -d”LARGE_MODEL” -ml -v28 -i”[Include Directory]”

2 AR2000 –r [IDL-Name].lib [IDL-Name].obj <Any other obj files added here …>

3 arm-elf-gcc –D CCP_ARM_THUMB_v410 -mcpu=arm7tdmi-s -mthumb-interwork -mthumb -fomit-frame-pointer -Wall -Os -c -o [IDL-Name].o [IDL-Name].c

4 arm-elf-ar rvs [IDL-Name].lib [IDL-Name].o <Any other o files added here …>

5 arm-elf-gcc -D CCP_ARM_v410 -mcpu=arm7tdmi-s -Wall -O2 -c -o [IDL-Name].o [IDL-Name].c

6 arm-elf-ar rvs [IDL-Name].lib [IDL-Name].o <Any other o files added here…>

7 arm-none-eabi-gcc.exe -c -fno-inline-small-functions -MD -mthumb -mcpu=cortex-m3 -ggdb -O2 -fsigned-char -mlittle-endian -D__GCC -DCCP_STM32FX0X441 -Wall -Wno-main [IDL-Name].c

8 AR2000 –r Conversion.lib Conversion.obj <Any other o files added here…>

Note: This table only shows how to compile the interface C-file. Any other source files that may be needed shall be compiled in the same way.

HWD Interface Types

Note: No separate H file is required when using format004A or higher.

Note: This table only shows how to compile the interface C-file. Any other source files that may be needed shall be compiled in the same way.


11078985 • Rev CA • Mar 201416

Table 6: Header file use with DP250 compiler v 4.1.0

File Name CCP_ARM_v410.h

File Content

#ifndef CCP_ARM_v410_H#define CCP_ARM_v410_H #ifdef CCP_ARM_v410 typedef unsigned char BOOL; typedef unsigned char U8; typedef signed char S8; typedef unsigned short U16; typedef signed short S16; typedef unsigned long U32; typedef signed long S32; #endif#endif

Important note: GUIDE is guaranteed not to define these IDL types. They shall only be defined when compiling the CCPs.

These files are either provided along with HWDs or need to be created by the CCP creator.HWD-specific header files for basic GUIDE types.

Table 4: Header file use with TI compiler v 5.2.5

File Name CCP_TI_v525.h

File Content

#ifndef CCP_TI_v525_H#define CCP_TI_v525_H #ifdef CCP_TI_v525 typedef unsigned char BOOL; typedef unsigned char U8; typedef signed char S8; typedef unsigned int U16; typedef signed int S16; typedef unsigned long U32; typedef signed long S32; #endif#endif

Table 5 Header file use with DP200/210 compiler v 4.1.0

File Name CCP_ARM_THUMB_v410.h

File Content

#ifndef CCP_ARM_THUMB_v410_H#define CCP_ARM_THUMB_v410_H #ifdef CCP_ARM_THUMB_v410 typedef unsigned char BOOL; typedef unsigned char U8; typedef signed char S8; typedef unsigned short U16; typedef signed short S16; typedef unsigned long U32; typedef signed long S32; #endif#endif

HWD Interface Types

Note: No separate H file is required when using format004A or higher.


11078985 • Rev CA • Mar 2014 17

RatatoskT3 is the tool used to create a starting point for the interface C code, a so called code skeleton, from an idl file created by the developer. The RatotaskT3 will generate a:

y C file, which is possible to modify during CCP creation. y H file which it is not advisable to modify during CCP creation. This file will also be automatically

generated by GUIDE during compile, and must then be the identical or at least equivalent in both cases.

RatatoskT3 accepts at most one argument.

If no argument is provided, RatatoskT3 will start in graphical mode using saved settings from the previous time it was used in graphical mode. If an argument is provided, it shall be in either the name of an IDL, or in the form of a comma-separated list of options.

y The list shall be contained within citation marks. No citations marks are needed (nor allowed) in the list.

y Each option is assigned a value using an equation character, option=value.

Possible options and values for CCP are (default values are underlined):

RatatoskT3

Basic Ratatosk T3 Usage

silent=yes/no run without starting the GUI

input=filename.idl input IDL-file name

c=yes/no generate c-file

h= yes/no generate h-file

If the “silent” option is set to “yes”, then the program will run in Command line mode, otherwise it will run in graphical mode.

Table 7 : Header files use with SCXXX-XXX compiler

File Name CCP_STM32FX0X.h

File Content

#ifndef CCP_STM32FX0X_H#define CCP_STM32FX0X_H

#ifdef CCP_STM32FX0X441 typedef unsigned char BOOL; typedef unsigned char U8; typedef signed char S8; typedef unsigned short U16; typedef signed short S16; typedef unsigned long U32; typedef signed long S32;

#ifdef FALSE #undef FALSE #endif #define FALSE ((BOOL)0U)#endif#endif

HWD-specific header files for basic GUIDE types.

Ratatosk T3 Interface Types


11078985 • Rev CA • Mar 201418

1. 1. Double-click RatatoskT3.exe.

2. Click browse to select your idl file.

3. Use the appropriate check boxes to select desired output (c and h files).

4. After making any changes to the idl file, click “Save” or “Reload” as appropriate, depending on whether the idl file is edited inside RatatoskT3 or in an external editor.

5. Click compile. New files output are generated.

Note: If files have been generated previously then those files will be overwritten.

6. To quickly look at the generated files, click once in the corresponding text-memo. The text will be shown in the large debug text memo in the lower right corner. A double click will instead delete the file (not implemented for all file types as of 5.10).

7. The next time RatatoskT3 is started in graphical mode the settings will be retained.

Basic Tutorial Set Up

CCP Tutorial


11078985 • Rev CA • Mar 2014 19

The following is an example for generate a C code skeleton in silent mode:

RatatoskT3.exe “silent=yes, input=MyFile.idl, c=yes,h=yes”

If you are unsure about what to write on the command-line, the simplest way forward is to start RatatoskT3 in graphical mode, make the selections you want and then copy the contents of the command line edit textbox.

This tutorial will build on the preceding lessons. During the tutorial, chapter IDL syntax below can be used as a detailed reference for the IDL file format.

The first step is to add rounding functionality to avoid the bug detected in the lessons. This will be done by first multiplying the calculation by 100, and then check if the result modulo 100 is:

a) greater than or equal to 50 orb) less than or equal to -50 orc) none of the above

y In the first case, the result will be increased by 1 y In the second case, the result will be decreased by 1

#include "./CCP_TI_v525.h"#include "./Conversion.h"Conversion_1C5B_SHARED_TYPE Conversion_1C5B_SHARED_INSTANCE;S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit){ S32 ScaledResult = 100 * (fahrenheit - 32) * 5 / 9; S32 DivResult = ScaledResult / 100; S32 ModResult = ScaledResult % 100; S32RoundingModifier; if(ModResult >= 50) { RoundingModifier=1; } else if(ModResult <= -50) { RoundingModifier = -1; } else { RoundingModifier= 0; } return DivResult +RoundingModifier;}

Command Line

Step 1: Adding functionality

Tutorial References

CCP Tutorial


11078985 • Rev CA • Mar 201420

The result of Step one should show the following:

Now the conversion from 0 degrees Fahrenheit is correct.

The second step intends to improve precision.

It shall be possible to control the number of decimals returned.

This is done by adding an additional input signal that is multiplied with the basic calculation. Furthermore, this additional input shall not be mandatory to connect. If it is not connected, a default setting shall come into effect, and a resolution of one tenth of a degree Celsius will be the result.

Note that in these examples the scale only affects the output. The input will not be scaled. In an actual CCP, the input would most likely be scaled as well. There could even be different scales for input and output values.

First, this requires a change to the idl file:

CCP_TI_v525 Conversion 002A{ #xclass Conversion { S32 Celsius (S32 fahrenheit, S32 scale := 10) { } }}

Step 2: Precision

Step 1:Adding functionality

CCP Tutorial


11078985 • Rev CA • Mar 2014 21

The added parameter scale has a default value of ten, which means that if no other input is connected, the resolution will be one tenth of a degree Celsius.

The idl file is now changed, so Ratatosk T3 must now be used to regenerate the code skeleton. The “Conversion.c” file will be overwritten by Ratatosk T3 so make sure to save a copy before it is regenerated. Then copy and paste the content of the saved Conversion_Celsius function before proceeding.

Now the C source must be modified to use the scale input:

#include "./CCP_TI_v525.h"#include "./Conversion.h"Conversion_20A8_SHARED_TYPE Conversion_20A8_SHARED_INSTANCE;S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit, S32 scale){ S32 ScaledResult = scale * 100 * (fahrenheit - 32) * 5/9; S32 DivResult = ScaledResult / 100; S32 ModResult = ScaledResult % 100; S32RoundingModifier; if(ModResult >= 50) { RoundingModifier= 1; } else if(ModResult <= -50) { RoundingModifier= -1; } else { RoundingModifier=0; } return DivResult +RoundingModifier;}

After re-adding the CCP to the GUIDE, it is possible to see that scale has a default value:

Step 2:Precision

CCP Tutorial


11078985 • Rev CA • Mar 201422

Next, take a look at the log values in the Service Tool; note that the values are multiplied by 10.

Step 3 expands the second step by allowing the GUIDE user to select what the default scale value shall be.

This is accomplished by adding a new data field to the Conversion xclass that is shared between all instances.

First, the idl file is updated with the following changes:

1. The data field defaultScale is added.

2. DefaultScale is given the initial value 10. (So that the behavior is the same as before, unless the GUIDE user decides to change it).

3. The property #shared is used in order to make this default shared between all instances of the Conversion xclass.

4. The property #set is used to allow the GUIDE user to set this value.

5. The property #get is used to allow the GUIDE user to get this value.

6. The property #shared is used in order to make this default shared between all instances of the Conversion xclass.

7. The default value of currentScale is set to 0. (This specific value will later be used to indicate that the defaultScale shall be used instead.)

CCP_TI_v525 Conversion 002A{ #xclass Conversion { S32 defaultScale := 10 <#shared #set #get> S32 Celsius(S32 fahrenheit, S32 currentScale := 0) { } }}

Step 3: User Controlled Default Scale

Step 2:Precision

CCP Tutorial


11078985 • Rev CA • Mar 2014 23

Since the idl file has been changed, it is necessary that RatatoskT3 be used to regenerate the code skeleton. The “Conversion.c” file will be overwritten by RatatoskT3 so make sure to save a copy before it is regenerated. Then copy and paste the content of the saved Conversion_Celsius function before proceed.

Now modify the C source to use the two new scale data fields (note that Conversion_DefaultScaleSET and Conversion_DefaultScaleGET are automatically generated):

#include "./CCP_TI_v525.h"#include "./Conversion.h"Conversion_3086_SHARED_TYPE Conversion_3086_SHARED_INSTANCE;S32 Conversion_DefaultScaleGET(Conversion * SELF){ return SELF->SHARED->defaultScale;}void Conversion_DefaultScaleSET(Conversion * SELF, S32 defaultScale){ SELF->SHARED->defaultScale = defaultScale;}S32 Conversion_Celsius(Conversion * SELF, S32 fahrenheit, S32 currentScale){ //if currentScale = 0 then defaultScale will be used instead: S32 scale = (currentScale)? (currentScale):(SELF->SHARED->defaultScale); S32 ScaledResult = scale * 100 * (fahrenheit - 32) * 5/9; S32 DivResult = ScaledResult / 100; S32 ModResult = ScaledResult % 100; S32RoundingModifier; if(ModResult >= 50) { RoundingModifier= 1; } else if(ModResult <= -50) { RoundingModifier= -1; } else { RoundingModifier= 0; } return DivResult +RoundingModifier;}

Step 3:User Controlled Default Scale

CCP Tutorial


11078985 • Rev CA • Mar 201424

The GUIDE application is changed in order to:

a) Call the conversion method once using a specific scale = 100b) Call the conversion method once using the default scalec) Using a second xclass instance, get the Default Scale d) Using the second xclass instance, set the Default Scale to 1000e) Using the second xclass instance, get the Default Scale again after the setf ) Using the first xclass instance, call the conversion method once using a specific scale = 100g) Using the first xclass instance, call the conversion method once using the default scale

Also, the methods are now only called once, rather than once each loop as before. The reason for using two xclass instances is only to demonstrate how shared data fields work.

After re-adding the CCP to the GUIDE, it is possible to see that scale has been renamed to currentScale and has a new default value.

Also there are two new methods:


CCP Tutorial


11078985 • Rev CA • Mar 2014 25

CCP Tutorial



11078985 • Rev CA • Mar 201426

The values are logged using the Service Tool:

As expected, when using “currentScale”, the output is not affected by the value of “defaultScale”.

When “defaultScale” is changed from 10 to 1000, the corresponding calculation gives a result that is ~100 times larger (Due to rounding, it is not exactly 100 times larger in this case).


CCP Tutorial


11078985 • Rev CA • Mar 2014 27

In this step the CCP will gain equal support for Kelvin, Celsius and Fahrenheit. This is accomplished by:

y The design will be made more modular in order to enable conversion from and to any of the three most popular temperature scales.

y A data type not available in GUIDE (float) will be used to store the most recently set temperature value. The storage format used is Kelvin.

Changes are made so that the generated code will not need to be modified after generation from RatatoskT3. This is accomplished by:

y Moving the basic implementation into its own C file. y Adding inline C code into the idl file calling the implementation C code.

Implementation C files are called ”MyImplementation.h” and ”MyImplementation.c”.

MyImplementation.h:

#ifndef MY_IMPLEMENTATION_H#define MY_IMPLEMENTATION_H

#include "CCP_TI_v525.h"

#define _KELVIN_ 0#define _CELSIUS_ 1#define _FAHRENHEIT_ 2

float MyGetTemp(S32 TempScale, float ActualKelvin, S32 dScale, S32 cScale);float MySetTemp(S32 TempScale, S32 Temperature);

#endif

MyImplementation.c:

#include "MyImplementation.h"#include <math.h>

#define C_OFFSET 273.15#define F_OFFSET 459.67#define F_TO_K_MUL (5.0 / 9.0)#define K_TO_F_MUL (9.0 / 5.0)

//Math.h as provided by TI does not provide a "round" function, //so it is implemented here using "floor"S32 round(float FloatValue){ return (S32)floor(FloatValue + 0.5);}

Step 4: Enabling Universal Conversions

CCP Tutorial


11078985 • Rev CA • Mar 201428

//Convert from Kelvin to specified temperature scale,//also allows scaling the resultfloat MyGetTemp(S32 TempScale, float ActualKelvin, S32 dScale, S32 cScale){ if(cScale) { dScale = cScale; } switch(TempScale) { case _KELVIN_ : return round(dScale * ActualKelvin); case _CELSIUS_ : return round(dScale * (ActualKelvin - C_OFFSET)); default /*_FAHRENHEIT*/ : return round(dScale * (ActualKelvin * K_TO_F_MUL - F_OFFSET)); }}

//Convert to Kelvin from specified temperature scalefloat MySetTemp(S32 TempScale, S32 Temperature){ switch(TempScale) { case _KELVIN_ : return Temperature; case _CELSIUS_ : return Temperature + C_OFFSET; default /*_FAHRENHEIT*/ : return (Temperature + F_OFFSET) * F_TO_K_MUL; }}

First compile MyImplementation.c using the command:

CL2000 MyImplementation.c -d”CCP_TI_v525” -pm -me -o3 q -g -pdr -pdv -pden -pdse225 -pds303 -d”LARGE_MODEL” -ml -v28 -i”C:\TI\v525\include” (assuming you have TI installed directly under C:\)

Then, update the idl file with the following changes:1. Since header files need to be included, these are added by using the #insert directive. In this case

the content is added to the upper part of the generated header file.

2. Since GUIDE will use the same CCP header file as the CCP interface code, it is necessary to protect the #includes so that they will not be expanded by the preprocessor during normal GUIDE compilation. This is done by using: “#ifdef CCP_TI_v525“. GUIDE will not define this macro, but the CCP compile command line will.

3. The “alien” member: “KelvinInternal” is added to each instance by using the verbatim field ({##}) directly inside the xclass.

4. KelvinInternal needs to be initialized. Alien data members can not be initialized in the same way as the basic GUIDE types can be in the idl format. Instead an initialization method can be used for this purpose. The initialization method is created by using the #init property on the xclass.

5. Inline C code, calling functions in “MyImplementation.obj”, is added to each method.

CCP Tutorial



11078985 • Rev CA • Mar 2014 29

After these changes, the generated C code no longer needs to be modified after generation by RatatoskT3.

CCP_TI_v525 Conversion 002A{

#insert <Into="H:HEAD">{##ifdef CCP_TI_v525 #include "CCP_TI_v525.h" #include "MyImplementation.h"#endif#} #xclass Conversion < #init{# SELF->ALIEN.KelvinInternal = 0.0;#} > { // "alien" data field used internally as the storage // format between conversions:{# float KelvinInternal;#} S32 defaultScale := 10 <#shared #set #get> void GetKelvin() { S32 kelvin <#out> S32 currentScale := 0 <#in>{# SELF->GetKelvin.kelvin = MyGetTemp( _KELVIN_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetKelvin.currentScale);#} } void GetCelsius() { S32 celsius <#out> S32 currentScale := 0 <#in>{# SELF->GetCelsius.celsius = MyGetTemp( _CELSIUS_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetCelsius.currentScale);#} } void GetFahrenheit() { S32 fahrenheit <#out> S32 currentScale := 0 <#in>{# SELF->GetFahrenheit.fahrenheit = MyGetTemp( _FAHRENHEIT_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetFahrenheit.currentScale);#} }


CCP Tutorial


11078985 • Rev CA • Mar 201430

void SetKelvin(S32 kelvin) {{# SELF->ALIEN.KelvinInternal = kelvin;#} } void SetCelsius(S32 celsius) {{# SELF->ALIEN.KelvinInternal = MySetTemp(_CELSIUS_ /*defined in "MyImplementation.h"*/, celsius);#} } void SetFahrenheit(S32 fahrenheit) {{# SELF->ALIEN.KelvinInternal = MySetTemp(_FAHRENHEIT_ /*defined in "MyImplementation.h"*/, fahrenheit);#} } }}

Since the idl file is now changed, RatatoskT3 must now be used to regenerate the code.

The C source no longer needs to be modified, but most comments have been removed here for the sake of brevity:

#include "./Conversion.h"Conversion_1E305_SHARED_TYPE Conversion_1E305_SHARED_INSTANCE;void Conversion_INIT(Conversion * SELF){ SELF->ALIEN.KelvinInternal = 0.0;}S32 Conversion_DefaultScaleGET(Conversion * SELF){ return SELF->SHARED->defaultScale;}void Conversion_DefaultScaleSET(Conversion * SELF, S32 defaultScale){ SELF->SHARED->defaultScale = defaultScale;}void Conversion_GetKelvin(Conversion * SELF){ SELF->GetKelvin.kelvin = MyGetTemp( _KELVIN_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetKelvin.currentScale);}

CCP Tutorial



11078985 • Rev CA • Mar 2014 31

void Conversion_GetCelsius(Conversion * SELF){ SELF->GetCelsius.celsius = MyGetTemp( _CELSIUS_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetCelsius.currentScale);}void Conversion_GetFahrenheit(Conversion * SELF){ SELF->GetFahrenheit.fahrenheit = MyGetTemp( _FAHRENHEIT_, //defined in "MyImplementation.h" SELF->ALIEN.KelvinInternal, SELF->SHARED->defaultScale, SELF->GetFahrenheit.currentScale);}void Conversion_SetKelvin(Conversion * SELF, S32 kelvin){ SELF->ALIEN.KelvinInternal = kelvin;}void Conversion_SetCelsius(Conversion * SELF, S32 celsius){ SELF->ALIEN.KelvinInternal = MySetTemp(_CELSIUS_ /*defined in "MyImplementation.h"*/, celsius);}void Conversion_SetFahrenheit(Conversion * SELF, S32 fahrenheit){ SELF->ALIEN.KelvinInternal = MySetTemp(_FAHRENHEIT_ /*defined in "MyImplementation.h"*/, fahrenheit);}

Compile Conversion.c using the command:

CL2000 Conversion.c -d” CCP_TI_v525” -pm -me -o3 -q -g -pdr -pdv -pden -pdse225 -pds303 -d”LARGE_MODEL” -ml-v28

Archive using the command:

AR2000 -r Conversion.lib Conversion.obj MyImplementation.obj


CCP Tutorial


11078985 • Rev CA • Mar 201432

After re-adding the CCP to the GUIDE, we can see the new methods:


CCP Tutorial


11078985 • Rev CA • Mar 2014 33

The GUIDE application is changed in order to:1. Use the Celsius set method for setting a temperature normally associated with the human body

temperature. (37 C / 310.15 K / 98.6 F).

2. Use the Fahrenheit get method with a specific scale of 100 to get a result with two decimals (= 9860).

3. Use the Kelvin get method with the default scale of 10 to get a result with one decimal. (= 3101.5, i.e. = 3102 after rounding).

4. Change the default scale from 10 to 1000.

5. Use the Celsius get method with the new default scale of 1000 to get a result with three decimals (= 37000).


CCP Tutorial


11078985 • Rev CA • Mar 201434

The values are logged using the Service Tool:

Note: The Value Presentation Multiplier has been used here to make the shown values more user-friendly:


CCP Tutorial


11078985 • Rev CA • Mar 2014 35

In this step, the embedded documentation functionality is demonstrated. In a CCP zip file it is possible to include documentation using any, or any combination, of the following file formats: TXT, PDF, CHM and HTML. The first part of the documentation file name must be the same as the name of the CCP.

HTML documentation will be explored further here.

First, create a HTML file named “Conversion.html” with the following content:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> <title>CCP Conversion manual</title></head><body><h1>CCP Conversion manual</h1>This is the manual for the temperature conversion CCP used in the CCP tutorial.<br>This is how to create the Conversion XClass:<br><img src="Create.bmp" alt="Create component picture"/><br>This is how to call a method in the Conversion XClass:<br><img src="Call.bmp" alt="Call method picture"/><br>See <a href="http://en.wikipedia.org/wiki/Temperature">this</a> Wikipedia article for more information about temperature.</body></html>

Now create two screenshot bmp files of how to create an XClass and of how to call a method in it. Call the bmp files “Create.bmp” and “Call.bmp”. Add the files: “Conversion. html”, “Create.bmp” and “Call.bmp” to the CCP zip file “Conversion.zip”.

Step 5: Documentation

CCP Tutorial


11078985 • Rev CA • Mar 201436

Note that the bmp files are not shown in the tree, they are not of a known type, but nevertheless they will be unpacked in the project folder.

Add the updated zip file to the GUIDE project. Inspect the project tree:Step 5: Documentation

CCP Tutorial


11078985 • Rev CA • Mar 2014 37

Double-click the documentation html file in the project tree. The html file will open in the user specified browser.

Step 5: Documentation

CCP Tutorial


11078985 • Rev CA • Mar 201438

The IDL Format

Character Sets

Basic Character Groups

Specific Character Groups

The IDL format is a text format and different parts of each element is built up of ASCII characters. Different subsets of characters are allowed in the different contexts of IDL

‘\t’ = tab ‘\r’=carriage return‘\n’=new line

A CCP Interface is expressed with an Interface Definition Language (IDL). An Interface definition consists of an element that can contain other elements in a nested hierarchy.

The general format of an element is as follows:

The rules for different parts of an element includes basic groups of characters

Specific character groups of elements

The exact content of each element depends of its type.

The value and properties groups will be defined separate for each element type

elements ’{’ element ’}’

’_’,’a’..’z’,’A’..’Z’letter

’0'..’9'digit

' ',’;’,'\t','\r','\n'end letter

dec int digit’-’ Example: 23746

Example: Trig_CCP_V012

Example: Into: H

type’#’

name

name letterletter,digit

end end letter

identifier letterletter,digit

letter,digit,’:’string ’ ” ’ ’ ” ’

Example: U32

Example: MyFormula

Example: U32 Speed ;

typeelement name value properties elements end

IDL Syntax


11078985 • Rev CA • Mar 2014 39

Interface Element

#xclass

The Interface definition consists of one element that can contain other elements in a nested hierarchy, where different element types are possible to use at each level of the hierarchy.

Top Element

The interface definition consists of one element on the highest level.

The interface element may contain one or more top elements.

Possible element types are #xclass and #insert.

An xclass defines a class with methods and internal state variables

version digit digit digit letter

typeelement name version elements end

Example:

IDL_Type IDL_CCP_Name 002A{ //top elements}

The type is #xclass

Example:

#xclass MyClass< // class properties>{ // class elements}

Element Types

IDL Syntax

properties ’<’ property ’>’

typexclass name properties elements end


11078985 • Rev CA • Mar 201440

#xclass Properties

#init

#process

An xclass property has the following format:

property name’#’verbatim

verbatim ’{#’ ASCII text ’#}’

The #init property states that the class shall have an Init function.

Optionally code may be passed on verbatim to the function if generated from the interface definition.

#init{# // Literal C code. Added to an Init function. //ExecutesoncebeforefirstupdateofGUIDEapplication.#}

Example:

Possible class elements are #init and #process

The #process property states that the class shall have a Process function.

Optionally code may be passed on verbatim to the function if generated from the interface definition.

Example:#process

{# // Literal C code. Added to a Process function. //ExecutesoncebeforeeachupdateofGUIDEapplication.#}

#xclass elements Possible #xclass elements are variables, verbatim elements and methods.

IDL Syntax


11078985 • Rev CA • Mar 2014 41

#xclass MyClass{ // class variables U16 classVar_1 <#shared> U16 classVar_2 := 456 <#shared>

// instance variables S16 instanceVar_1 <#get #set>

// alien variables {# double Scale; #}

A Variable has the following format:

init value ’:=’ dec int

Valid variable types are U32, S32, U16, S16, U8, S8 or BOOL.

It is also possible to define instance variables of other data types than those that are allowed in the interface definition, so called alien variables. This is done with a verbatim element.


Possible properties are: #shared the variable is a class variable shared between all instances of the #xclass

#get the variable will have a Get method automatically generated to read its value#set the variable will have a Set method automatically generated to write a value to it

A variable without the #shared property is a private instance variable i.e. it is used only by the instance of the #xclass.

The init value may be used to assign a value at initialization

Variable Formats

Verbatim Formats

Example:

typevariable name init value properties end

IDL Syntax


11078985 • Rev CA • Mar 201442

Methods

The method type is the return type of the method. Valid types are U32, S32, U16, S16, U8, S8, BOOL or void. The return type void indicates that the method doesn’t return any value.

#xclass methods have the following format:

typemethod name arg list elements end

arg list ’(’ argument ’)’

’,’


Valid argument type is U32, S32, U16, S16, U8, S8 or BOOL. Possible properties are:

#in — the argument is an input#out — the argument is an output

Property #in is default until the first #out is specified after which #out is default.

Important Note: All input arguments must come first in the list so no #in property is allowed after an #out property.

The optional init value is may be used to assign a value at initialization. It can only be used with input arguments. The value will be used if no input connection has been assigned to that argument.

Example:

#xclass MyClass{ // method BOOL C1_Func_1(U16 argIn_1 := 123, U16 argOut_1<#out>, U16 argOut_2) { // method elements }}

Init value

typeargument name init value property

IDL Syntax


11078985 • Rev CA • Mar 2014 43

Method Variables A method may have method variables.


Valid variable type is U32, S32, U16, S16, U8, S8 or BOOL.

Possible properties are: #in — the variable is an input variable to the method of the #xclass#out — the variable is an output variable from the method of the #xclass

Using method variables with #in and #out properties is an alternative way of passing data to and from the method, to avoid very long argument lists.

A variable without any property is private instance variable for the method i.e. it is used only by the instance of the #xclass and only by the method it’s defined in.

The init value may be used to assign a value at initialization.

Note: variables with the property #out are not allowed to have an init value.

Example:

#xclass MyClass{ // method BOOL C1_Func_1(U16 argIn_1, U16 argOut_1<#out>, U16 argOut_2) { // method variables BOOL c1_VarOut_1 <#out> S16 c1_VarIn_1 := 123 <#in> U8 c1_VarPrivate }}

typevariable name init value properties end

IDL Syntax


11078985 • Rev CA • Mar 201444

Method Verbatim Text


#xclass MyClass

{ // method BOOL C1_Func_1 (U8 argIn_1, U16 argOut_1<#out>, U16 argOut_2) { // verbatim element {#return My_C1_Func_1(&SELF,argIn_1,argOut_1,argOut_2); #} }}

#insert The insert element makes it possible to pass on verbatim text to files that are generated from the interface definition.

typeinsert properties verbatim end

property name ’=’ string


Optionally inside a method, code may be passed on verbatim to the method function if it is generated from the interface definition.

Example:

The type is #insert

Valid property is Into=”H:HEAD” which directs the verbatim text to the beginning of a header file.

Example:

#insert <Into="H:HEAD">{# #include "CCP_TI_v525.h" // For S8, U8, S16.... #include "CCP_FmtXmpl.h" // For user defined types.#}

IDL Types


11078985 • Rev CA • Mar 2014 45

Change Log

IDL Change Log

003A versus 002A

GUIDE Support for IDL Formats

GUIDE Version Highest Supported IDL Format

5.0 002A

5.1 003A

6.0 004A

y Into = H: TAIL

y Into = C: HEAD


11078985 • Rev CA • Mar 201446

IDL Change Log

003A versus 002A (con’t) y Into = C: TAIL


11078985 • Rev CA • Mar 2014 47

004A versus 003A

IDL Change Log

y #DONTDEFINEGUIDETYPES

When using format 004A and later, the following types are automatically supported automatically generated typedefs for GUIDE types:

y CCP_TI_v525 y CCP_SGL_Q1202 y CCP_ARM_THUMB_v410 y CCP_ARM_v410 y CCP_STM32FX0X441

Example for CCP_TI_v525:Note: No separate H file is required when using format004A or higher.


11078985 • Rev CA • Mar 201448

004A versus 003A (con’t)

IDL Change Log

If that is not desirable, then use #DONTDEFINEGUIDETYPES to disable this:

Input arrays can have variable length; the length is then depending on the length of the connected array in GUIDE graphical code.

Array Types


11078985 • Rev CA • Mar 2014 49

IDL Change Log

Array Types (con’t)


11078985 • Rev CA • Mar 201450

New Types

IDL Change Log

Four new types are available for CCP parameters:

y U64 y S64 y F32 (float) y F64 (double)


11078985 • Rev CA • Mar 2014 51

New Types (con’t)

IDL Change Log

y Into = H: BODY

y #NV

Private function members can now be stored in NV memory. Currently, only the basic integer types are supported.


11078985 • Rev CA • Mar 201452

New Types (con’t)

IDL Change Log

Some keywords, such as ‘into’, are case-insensitive in versions 004 and later


11078985 • Rev CA • Mar 2014 53

CCP Macros

RatatoskT3 Version 6.0

A few new macros have been added to simplify the writing of interface C code:

This change does not depend on the used IDL format.


11078985 • Rev CA • Mar 201454

CCP Macros (con’t)

RatatoskT3 Version 6.0

y CCP_METHOD refers to the local CCP method. It is mainly intended for internal use by other macros.

y CCP_METHOD_DATA takes as its argument the name of one of the method’s data fields. The macro expands the full name of that data field.

y CCP_METHOD_ARRAY_LENGTH takes as its argument the name of one of the method’s array data fields. The macro returns the length of the array data field.

y CCP_METHOD_ARRAY_INDEX takes as its argument the name of one of the method’s array data fields. The macro expands the full name of that data field and array index.

y CCP_SHARED refers to the shared struct for all CCP instances of the same class. It is mainly intended for internal use by other macros.

y CCP_SHARED_DATA takes as its argument the name of one of the shared data fields. The macro expands the full name of that data field.

y CCP_INST_DATA takes as its argument the name of one of the class instance’s data fields. The macro expands the full name of that data field.

y CCP_ALIEN_DATA takes as its argument the name of one of the class instance’s alien data fields. The macro expands the full name of that data field.


11078985 • Rev CA • Mar 2014 55

Problem Possible Reason Solution

C Compile error when compiling in GUIDE

C header files that contain definitions conflicting with the GUIDE definitions are included in the CCP zip file.

Avoid adding C header files in the CCP zip file.

If you absolutely need to add a header file, try to make it as small and unique as possible.

C Compile error when compiling in GUIDE, but only when another CCP is also included in the project.

C header files that contain definitions conflicting with the other CCP’s definitions are included in the CCP zip file.

Avoid adding C header files in the CCP zip file.

If you absolutely need to add a header file, try to make it as small and unique as possible.

C Link error when compiling in GUIDE. The name of the shared data structure is part of the error message.

The idl file was modified after it was used to generate code.The generated error is an intentional safety feature. The reason is to avoid accidental interface/implementation mismatches.

Regenerate and recompile code from idl. This will overwrite the interface c-file.

C Link error when compiling in GUIDE. The name of a method or XClass is part of the error message.

The name was changed in the C source.

Never change names that have been generated from idl.

Functionality has been changed, and the GUIDE compilation works, but it seems like the functionality is the same as before the functionality change.

The lib file might have been created in append mode, and therefore contains both the old and the new functionality. Since the old functionality exists closer to the beginning of the lib file, that is the version that will be linked into the application.

Always delete the old lib file before creating a new one.

GUIDE compile error saying that <Some name> “IS UNKNOWN”

Wrong spelling or case. All names are case sensitive.

Use the same spelling and case as in the project manager tree.

This section lists solution to common problems that might occur.Troubleshooting


11078985 • Rev CA • Mar 201456

• A Compiled Code Package (CCP) provides one or more "external class" (XClass) types that can be used within a GUIDE application.

• CCPs can be imported into the GUIDE environment, for use in a GUIDE application, as shown in the example below:

y Multiple CCPs, each containing multiple XClasses can be used in a GUIDE application project. The condition is that all the used CCPs have a type that is allowed by the used HWD.

y An instance of an XClass is created in the GUIDE application using the component: “Create Externally Defined Class”, found under “Connection” in the Component tree.

y Multiple instances of each XClass can be created in a GUIDE application.

y Each XClass supports member methods that can be conditionally called from the GUIDE application by using the component: ”Call Method Of Externally Defined Class”, found under “Connection” in the Component tree.

y The XCLASS output signal from the CREATE block is routed to each method call, to associate it with a particular instance.

y All other input and output signals for the CALL block are limited to standard GUIDE data types (BOOL, S8, U8, S16, U16, S32, U32). Since GUIDE 6.0, it can also be S64, U64, F32 and F64.

y Internally, the member functions can use any standard or abstract data type.

y Each member method is supported by standard C code that is compiled separately from the GUIDE application.

y Each CCP is a ZIP file that contains (at least) a LIB file and an IDL file. The LIB file contains the object code to support the C code functions. The IDL file is used by GUIDE to generate the interface header. The first part of the LIB and IDL file names must be the same as the CCP name.

y Documentation files can be added to CCPs using the following file formats: TXT, PDF, CHM and HTML. The first part of the documentation file name must be the same as the CCP name.

y Other files can also be added to the CCP, but this is not recommended, and they will not be shown in the project tree.

Quick Facts


11078985 • Rev CA • Mar 2014 57

y IDL stands for Interface Definition Language, and many different IDL formats exist. The IDL format described in this manual is specific for the interface between GUIDE and CCP.

y Each CREATE block added to a GUIDE application produces an allocation of static memory to support an instance of the XCLASS.

y Each XClass instance corresponds to a struct variable in the C language.

Quick Facts


11078985 • Rev CA • Mar 201458

Add Compiled Code Package, 11API, 4-5, 15, 4-5, 15Architecture, 15Archive Commands, 15ASCII, 38

Basic Character Groups, 2, 38, 2, 38Basic Lessons, 2, 7, 2, 7Basic Ratatosk T3 Usage, 2, 17, 2, 17Basic Tutorial Set Up, 2, 18, 2, 18

C-code, 2, 5, 10, 2, 5, 10C-code Modification Process, 2, 10, 2, 10C-compiler, 2, 10, 2, 10CCP Conversion, 35CCP Interface, 2, 8, 28, 38, 2, 8, 28, 38Character Sets, 2, 38, 2, 38Compiler Version, 5, 7, 15, 4-5, 7, 15Controlled Default Scale, 2, 22-26, 2, 22-26Conversion XClass, 22, 35, 22, 35Create Compiled Code Packages, 1Create Externally Defined Class, 5, 12, 46, 5, 12, 46Creator Expectations, 2, 5, 2, 5

Datatypes, 2, 8, 15, 2, 8, 15Default Scale, 2, 22-26, 33, 2, 22-26, 33DefaultScaleGET, 23, 30, 23, 30DefaultScaleSET, 23, 30, 23, 30

Element Types, 2, 39, 2, 39Enabling Universal Conversions, 2, 27-29, 2, 27-29File Name, 16, 35, 46, 16, 35, 46Functionality, 2, 4, 7, 19-20, 35, 45, 2, 4, 7, 19-20, 35, 45

GUIDE Create Compiled Code Packages, 1GUIDE Interface, 2, 5, 15, 5GUIDE Microcontroller, 7GUIDE Project, 2, 11-14, 36, 2, 11-14, 36

Header, 2, 7-8, 10, 16, 28, 44-46, 2, 8, 10, 16, 28, 44-46HWD Error, 8, 10HWD Interface Types, 2, 16, 2, 15-16

The IDL, 2, 12, 18-23, 27-28, 30, 38, 45-47, 2, 4, 12, 18-23, 27-28, 30, 38, 45-47IDL-file, 8, 11, 17, 8, 10, 17IDL CheckSum, 8-9The IDL Format, 2, 28, 38, 47, 2, 28, 38, 47IDL Name, 8-9IDL Types, 15-16, 44, 15-16, 44IDL Version, 8-9Implementation C, 27Interface, 2, 5, 7-8, 15-17, 28, 38-41, 44-47, 2, 4-5, 7-10, 15-17, 28, 38-41, 44-47Interface Between CCP, 7, 2, 7-10Interface Definition Language, 8, 38, 47, 8, 38, 47Interface Element, 2, 39, 2, 39

Locate RatatoskT3, 8

Method of Externally Defined Class, 5, 12, 46, 5, 12, 46Method Variables, 3, 43, 3, 43

Method Verbatim Text, 3, 44, 3, 44Modification of C-code, 2, 10Multiple CCPs, 46

P1Compiler, 8P1Tools, 8

Ratatosk T3, 2, 17, 21, 2, 17, 21Ratatosk T3 Interface Types, 2, 17, 2, 17Revision History, 3Risk Reduction, 2, 4, 2, 4

S32 Celsius, 7, 20, 22, 29-31, 8, 20, 22, 29-31S32 DivResult, 19, 21, 23, 19, 21, 23S32 RoundingModifier, 19, 21, 23, 19, 21, 23S32 ScaledResult, 19, 21, 23, 19, 21, 23S32 Temperature, 27-28, 27-28SetCelsius, 30-31, 30-31SetFahrenheit, 30-31, 30-31SetKelvin, 30-31, 30-31Simple Checkpoint, 12Specific Character Groups, 2, 38, 2, 38

Top Element, 2, 39, 2, 39Tutorial ReferenceS, 2, 19, 2, 19Type IDL, 39

User Controlled Default Scale, 2, 22, 2, 22

Value Presentation Multiplier, 34Variable Formats, 3, 41, 2, 41Version, 4-5, 7-8, 15, 45, 4-5, 7-9, 15, 45

XCLASS, 2-3, 7-8, 20, 22, 24, 28-29, 35, 39-47, 2, 8-9, 20, 22, 24, 28-29, 35, 39-47XCLASS Conversion, 7-8, 20, 22, 29, 8-9, 20, 22, 29

ZIP-program, 11, 10

Index


11078985 • Rev CA • Mar 2014 59

Notes

Comatrolwww.comatrol.com

Schwarzmüller-Inverterwww.schwarzmueller-inverter.com

Turolla www.turollaocg.com

Valmovawww.valmova.com

Hydro-Gear www.hydro-gear.com

Daikin-Sauer-Danfosswww.daikin-sauer-danfoss.com

Danfoss Power Solutions is a global manufacturer and supplier of high-quality hydraulic and electronic components. We specialize in providing state-of-the-art technology and solutions that excel in the harsh operating conditions of the mobile off -highway market. Building on our extensive applications expertise, we work closely with our customers to ensure exceptional performance for a broad range of off -highway vehicles.

We help OEMs around the world speed up system development, reduce costs and bring vehicles to market faster. Danfoss – Your Strongest Partner in Mobile Hydraulics.

Go to www.powersolutions.danfoss.com for further product information.

Wherever off -highway vehicles are at work, so is Danfoss.

We off er expert worldwide support for our customers, ensuring the best possible solutions for outstanding performance. And with an extensive network of Global Service Partners, we also provide comprehensive global service for all of our components.

Please contact the Danfoss Power Solution representative nearest you.

Products we off er:

Bent Axis Motors

Closed Circuit Axial Piston Pumps and Motors

Displays

Electrohydraulic Power Steering

Electrohydraulics

Hydraulic Power Steering

Integrated Systems

Joysticks and Control Handles

Microcontrollers and Software

Open Circuit Axial Piston Pumps

Orbital Motors

PLUS+1® GUIDE

Proportional Valves

Sensors

Steering

Transit Mixer Drives

Local address:

Danfoss can accept no responsibility for possible errors in catalogues, brochures and other printed material. Danfoss reserves the right to alter its products without notice. This also applies to products already on order provided that such alterations can be made without changes being necessary in specifications already agreed.All trademarks in this material are property of the respective companies. Danfoss and the Danfoss logotype are trademarks of Danfoss A/S. All rights reserved.

Danfoss Power Solutions GmbH & Co. OHGKrokamp 35D-24539 Neumünster, GermanyPhone: +49 4321 871 0

Danfoss Power Solutions ApSNordborgvej 81DK-6430 Nordborg, DenmarkPhone: +45 7488 2222

Danfoss Power Solutions (US) Company2800 East 13th StreetAmes, IA 50010, USAPhone: +1 515 239 6000

Danfoss Power Solutions Trading(Shanghai) Co. Ltd.Building #22, No. 1000 Jin Hai RdJin Qiao, Pudong New DistrictShanghai, China 201206Phone: +86 21 3418 5200

11078985 • Rev CA • Mar 2014 www.danfoss.com © Danfoss A/S, 2014-03

plus+1® guide create compiled code packages user manual

Documents