CAPL

C - A - P- L
CAN Access Programming Language (CAPL) => Preferred,
Communication Application Programming Language (CAPL)
CAPL - What & Why ????
“WHAT” is CAPL

 CAPL is a procedural and event driven programming language that allows to

setup a customized Platform for testing distributed system software, by
emulating the behavior of nodes.

“WHY” do we need CAPL

 Allows to create, modify, and maintain CAPL programs which can interface
with a wide variety of inputs, outputs and other functions.

 Analyze specific messages or specific data

 Analyze data traffic E.g. -> Bus Load
 Create and modify the tool’s measurement environment
 Create a black box to simulate the rest of the network
 Create a custom module diagnostic or service tool
 Program a functional gateway between two different networks

This is definitely cheaper and faster way of testing the ECU than in a prototype car!
Residing/Working of CAPL

 Other Programming Languages like C,C++…… are working WITH

Application Where as CAPL is working FOR Application.
Use of CAPL

 The CANalyzer or CANoe tool itself, without CAPL programs, is enough to execute
simple measurement and analysis.
 With CAPL programs involved, measurement and analysis is greatly extended for
CAN communication. One area that the tool cannot perform without CAPL is
analysis that involves timing. CAPL can make analysis more efficient with the help
of Timers.
Relation between C, C++ & CAPL

Similarities of ‘C’

 CAPL uses the same looping constructs and the Control structures used in C.
 Supports standard C syntax.
 CAPL extends the C foundation with extra network-specific functions and
data types.

Dissimilarities of ‘C’
 All Local variables are static.
 Allows Function Overloading.
 Event Driven programming.
 No Support for pointers and dynamic memory handling functions
(malloc/calloc).
 No distinction between upper and lower case function names.
CAPL Browser Orientation
 Can declare and initialize global variables.
 Function invoking, event triggering and
processes execution are not allowed
CODE Compilation

There are three ways to compile a CAPL program

 Press the ‘F9’ key while in the CAPL Browser.

 Choose Compile or Compile All from the Compiler menu or shortcuts.
 Click on the compile shortcut icon on CANalyzer or CANoe’s Tool Bar.

Choosing Compile All compiles all of the CAPL programs that are currently open in the
CAPL Browser one at a Time.

 A CAPL program is only found in one source file with the *.CAN extension that
requires no previously compiled functions from library files for compilation.
 After the CAPL program is first compiled, a binary source file with the extension
*.CBF (CAPL Binary File) is created in the same directory as the *.CAN file.
Run-Time Errors
A number of CAPL run-time errors are monitored. Some of these run-time errors are
as follows:
 Division by zero.
 Exceeding the upper or lower limits of the array.
 Exceeding the upper or lower limits of the offset in the data range of messages.
 Stack overflow when CAPL subroutines are called.

 If an run-time error is detected, the intrinsic (built-in) function runError() is called.

This stops the measurement and outputs information to the Write window with the
name of the CAPL program, the type of error and an error number.
The output in the Write window might look like the following
Start of measurement 04:02:33 pm
Bus with 500000 BPS.
PRG (CAPL): < MYPROG > generated an error at CAPL pos: 1.
Locate with CAPL browser option: Find runError - err number -> 1.
Unknown error
measurement stopped
End of measurement 04:03:56 pm
80/20 Rule

1. Output 11. on sysvar

2. Write 12. on envVar
3. Message 13. on signal
4. Settimer 14. BusLoad
5. TimeToElapse 15. openPanel
6. cancelTimer 16. closePanel
7. startLogging 17. isTimerActive
8. stopLogging 18. Halt
9. getValue 19. Stop
10. putValue 20. sysExit
Write Window
WRITE

 Outputs a text message to the Write window. Write is based on the C function
printf..
Syntax: void write(char format[], ...);

Examples

float f=123.456;

on key 'h'
{
write("Hello World!");
write("f = %5.3f",f);
write("format is not supported for the given variable");
write(“%d”,f);
write(“%c”,f);
}
OUTPUT Function
OUTPUT

 Outputs a message, or an error frame from the program block onto the CAN bus.
Syntax: output(message msg);

Example

Variable Declaration:
• message 0x7ED ABC;

Example:
on key F1
{
ABC.byte(0) = 0x01;
ABC.byte(1) = 0x02;
ABC.byte(2) = 0x03;
ABC.byte(3) = 0x04;
output(ABC);
}
EVENTS
 An event is a specific occurrence, or a condition, that may invoke some necessary
action.

Events
 pressing START or STOP
 Keyboard entry
 CAN message reception
 Timer Timeout
 Error frame events
 CAN controller events
 System (tool) events
 user input via graphic panel (CANoe)
CAPL Interfaces
EVENTS (Continue..)
Events

System Specific User defined

CAN message
System (Prestart, Start, Stop)
Timer
CAN Controller
Keyboard
Error frame
Environment
Function
Points to concentrate on Event
 NO priority for Events
 Events won’t stop in middle of execution
 A specified CAN channel has precedence over the absence of a CAN
channel.
 A specified message ID number has precedence over a * symbol wildcard.
 Message event definitions are more involved than Keyboard events
 Event procedures cannot return a value.
System Defined Events -> System Specific

 Executes before Starting of Node and Ending of node

4 Events

 Prestart  on preStart
 Start  on start
 PreStop  on preStop
 Stop  on stopMeasurement
On Pre-Start Event

On Prestart
 Used for event handling before the start of CANalyzer/CANoe measurements.

Limitations

 Can able to read data from files, initialize variables, or to print characters in the
Write window. Other actions, such as outputting a message onto the bus, are
not available in the on preStart event procedure.

Example

on preStart
{
// Set Start Delay to 10 seconds
setStartdelay(10000);
write("Node Activated after 10sec");
}
On Start Event

On Start

 Event handling after pre-Start is executed and Measurements are started.

 In Start Initialize environment variables, timers and output messages.

Example

On start {
setTimer(t1, 20);
msg1.byte(0)=0x20;
output(msg1);
}
On Prestop & On stopMeasurement Events

on preStop on preStop
{
message ShutdownReq m;

output(m);
DeferStop(1000); // measurement is stopped if ACK has not
// yet been received after one second
}

on message ShutdownAck
{
CompleteStop();
}

on stopMeasurement

stopLogging(); // stops all logging blocks

CAN Controller Events -> System Specific

 Represents the error state of the CAN controller

4 Events

 Bus Off detected  on busOff

 Error Active detected  on errorActive
 Error Passive detected  on errorPassive
 Warning Limit detected  on warningLimit
Error Frame Event -> System Specific
 Used to keep statistics on the number and timing of error frames

In the following example it shall be checked if the error frame is a transmission or a

reception error.
This information is set in the 5th bit of the ECC register. A transmission error is
indicated by 0, a reception by 1. To get the 5th bit you have to mask the ECC register
with 0x20.
on errorFrame
Example
{
switch (this.ecc & 0x20)
{
case (0x20): // in case of reception error
write ("%d Ch %d RxErr", this.time, this.can);
return;
case (0): // in case of transmission error
write ("%d Ch %d TxErr", this.time, this.can);
return;
};
}
CAN message -> User Defined
 A message is a piece of data, that encapsulates information that is specific to
an entity (ECU/node).
 Messages have to be declared in the variable section before using them.

Syntax : message <message identifier or name> <variable name>

Declaring Messages in CAPL with a Database

message TGWSource currentSrc ;

message 0x100 currentSrc;
message TGWSource currentSrc1, currentSrc2;
Declaring Messages in CAPL without a Database
message 0x317 currentSrc = { DLC = 8 };
or
currentSrc.DLC = 8;

message 0x317x currentSrc = { DLC = 8 }; //for 29-bit ID

MESSAGE Event (Continue…)

Example
On message : Reacts upon receiving of message
variables
{
message 0x555 ABC;
}

on message * on message ABC

{ {
write(“Responds to Every Message”); write(“Responds to ABC Message ”);
setTimer(t1,100); //Calling Timer setTimer(t1,100); //Calling Timer

/*** /***
some event handling code some event handling code
***/ ***/
} }
Message Selectors
Ways of Accessing Message
Accessing Data of a Message

 Using Signals if Database is present

• Example: int myvalue; // declare an integer
myvalue = messagename.signalname;

 CAPL uses the Intel format

Keywords:
 BYTE (8 bits)
 WORD (16 bits)
 LONG (32 bits)
 DWORD (32 bits)

Messagename.BYTE(0) 0x6E
Messagename.WORD(0)0x16E
Messagename.LONG(4)0x23C9B57A
TIMER Event

SetTimer
 Sets a timer for the specified time duration.
Syntax: setTimer(Timer t, long duration);
Timer Variable Declaration:
1. msTimer ABC;
2. Timer ABC;

Parameters : Variable of type Timer or msTimer and the duration of the timer in
units of seconds or milliseconds.
Example

1st 2nd 3rd

Variables on start on timer ABC

{ { {
mstimer ABC; setTimer(ABC, 50); /* Event handling Code*/
} } }
TIMER Event -> Cancel Timer (Continue…)
Canceltimer
 Stops an active timer that has been set with setTimer(). This prevents the timer
event procedure from being executed.

Syntax: cancelTimer(Timer t);

Parameter: timer or msTimer variable

Example
1st 2nd 3rd

Variables on start on timer ABC

{ { {
mstimer ABC; setTimer(ABC, 50); /* Event handling Code*/
} } }

on key ‘a’
{
cancelTimer(ABC);
}
TIMER Event (Continue…)

 If you are trying to reset a timer, and that timer has not yet expired, you will
get a run-time warning in the Write window of CANalyzer/CANoe and your
attempt to reset that timer will be ignored. To reset a timer that is still
running, call the cancelTimer() function first and then set new timer with
setTimer() function.

Timetoelapse
 Returns a value indicating how much more time will elapse before
an on timer event procedure is called

Synatx :- long timeToElapse(timer t) (Form 1)

Istimeractive
 Return value indicates whether a specific timer is active.

Syntax :- int isTimerActive(timer t)

How to Respond TO A MESSAGE AFTER A DELAY?
Example: To turn off dome light 5 seconds after door is closed
1.Declare a timer and delay variable
variables
{
timer delayTimer; // seconds-based timer
long delayTimerPeriod = 5; // initialize delay of 5 seconds
}
2.Create the on message event procedure that sets the timer if the
doors are closed
on message doorState
{
if (this.Closed == 1) // door is closed
setTimer(delayTimer, delayTimerPeriod);
else // door is opened
{ // do this if door is opened
...} }
ON KEY Event

 On key event : Occurs on press of a key on keyboard

Example

on key ‘b’
{
Write(“pressed key ‘b’”);
}
Miscellaneous

 Types of CAPL Nodes

Panel Creation
 System Variables
 EnvironMent Variables

OSEKTP(Flow Control Using CAPL)

File Operations

GateWay
Environment variables

 Environment variables make connection possible between elements on the panel

and the associated CAPL program.
 Environment variables are used in CANoe to represent external values on the
network, such as the position of a switch.
 These are defined in an associated database with the CANdb++ or CANdb
Database Editor, and can be read and changed by a CAPL program. Because they
are accessible to all events and functions in a CAPL program,
 They are considered as global variables.
 These global variables are also available to all CAPL programs in the same
CANoe configuration and not just one single CAPL program.

Note: It is considered a bad programming technique to use environment variables to

exchange information between CAPL programs, because CAPL programs normally
represent nodes on a CAN network. In reality, environment variables do not exist on
a physical CAN system. Therefore, use only CAN messages to exchange data
between CAPL programs.
Examples

1) To Test the Cyclic Time of Two Messages

2) To Fire any Diagnostic Message continuously for every 1sec
3) To Calculate Seed Key and Unlock Security.