CAPL BASICS

 CAPL
CAN Access Programming Language

 CAPL Programming
The CAN Access Programming Language CAPL is a C-like programming
language,
which allows you to program CANoe for individual applications.

 Introduction to CAPL
CAPL, the CAN Access Programming Language, allows you to quickly
develop code that makes CANalyzer or CANoe simulations more powerful.
CAPL  is  a  procedural  language  whereby  the  execution  of  program  blocks  is 
con-trolled by events. These program blocks are known as event procedures.
The program code that you define in event procedures is executed when the event
occurs.

For example, you can send a message on the bus in response to a key press (on
key), track the occurrence of messages on the bus (on message), or execute certain
actions cyclically (on timer).

 Introduction to CAPL
A CAPL program consists of two parts:
       1. Declare and define global variables
       2. Declare and define user-defined functions and event procedures

 CAPL Program Organization

CAPL programs have three distinct parts:
            1. Global Variable Declarations
            2. Event Procedures
            3. User-Defined Functions

 CAPL Variables
Data types available for variables include integers
(dword, long, word, int, byte, char), floating point numbers (float anddouble),
CAN messages (message) and timers (timer or msTimer). Except for the timers, all
other variables can be initial-ized in their declarations.
  variables {
      int msgCount; // Is set to 0 at measurement start
      message 34 sendMsg = { // Declare message with Id 34
      dlc = 1, // Set Data Length Code = 1
      byte(0) = 1 // Set 1st data byte = 1
      };
 }
 CAPL Variables
Variables can be initialized when they are declared, whereby you can use either
simple notation or brackets {}. With the exception of timers, the compiler
initializes all variables with default values (unless otherwise defined: 0).
CAPL permits the declaration of arrays (arrays, vectors, matrices), analogous to
their declaration in the C programming language.
variables {
     int vector[5] = {1,2,3,4,5};
     int matrix[2][2] = {{11,12},{21,22}};
     char progname[10] = “CANoe“;
    }
 CAPL Variables

Variables  of  the  type  timer  (based  on  seconds)  or  msTimer (based on

milliseconds) serve to generate time events. Timer variables are not automatically
initializedat  the  program  start,  rather  they  must  be  "set"  explicitly  with  the 
function setTimer().
     variables {
     timer delayTimer; // Declaration of a second timer ...
     msTimer cycTimer; // ... and a millisecond timer
     }
     ...
     setTimer(delayTimer,3); // Set timer to 3 sec
     setTimer(cycTimer,100); // Set timer to 100 msec
     ...
 Declaration of Messages

Messages  to  be  output  from  the  CAPL  program  are  declared  with  the 
key  word message. The complete declaration includes the message identifier or -
when work-ing with symbolic databases - the message name. For example, you
might write the following to output messages on the bus that have identifier A
(hex) or 100 (dec) or the message EngineDatadefined in the database.

            message 0xA m1; // Message declaration (hex)

            message 100 m2; // Message declaration (dec)
            message EngineData m3; // Symbolic declaration
            message * wcrd; // Declaration without Id
            ...
            output(m1); // Transmit message m1
            output(m2); // Transmit message m2
            output(m3); // Transmit message m3
            wcrd.id = 0x1A0; // Define Id...
            output(wcrd);

  Declaration of Messages

It is possible to access control information for the CAN message objects using the
following component selectors:
            ID                    Message identifier
            CAN               Chip number
            DLC               Data Length Code
           DIR   Direction of transmission, possible values: RX, TX,
TXREQUEST.
            RTR               Remote Transmission Request; possible values: 0 (No
RTR), 1                                 (RTR)
            TYPE                         Combination of DIR and RTR for efficient
evaluation. 
                                    (TYPE = (RTR << 8) | DIR )
            TIME                         Time point, units: 10 microseconds
 Event Procedures

You can react to the following events in CAPL using event procedures:
            Event                                      Event procedure                  
            Receipt of a CAN message                 on message{}
            Press of a key                                      on key{}
            Initialization of measurement (before meas-urement start)
                                                            on preStart{}
            Measurement start                   on start{}
            End of measurement               on stopMeasurement{}
            CAN controller goes to ErrorActive  on errorActive{}
            CAN controller goes to ErrorPassive on errorPassive{}
            CAN controller reaches the warning limit      on warningLimit{}
            CAN controller goes to Bus Off        on busOff{}
            Elapse of a timer                                 on timer{}
            Occurrence of an error frame                          on errorFrame{}
            Environment variable change                          on envVar{}
 React to Messages

The  event  procedure  type on message  is  provided  to  react  to  the  receipt  of
CAN messages in the CAPL nodes.
            on message 123                      React to message 123 (dec),
                                                Receiving chip is not considered
            on message 0x123      React to message 123 (hex);
                                                receive chip is not considered
            on message EngineData        React to message EngineData
            on message CAN1.123          React to message 123,
                                                if it is received by chip CAN1
            on message *              React to all messages
            on message CAN2.* React to all messages
                                                that are received by chip CAN2

            on message 100-200   React to all messages

                                                with identifiers between 100 and 200
 Example for React to Messages

            on message CAN1.34 {

                        message CAN2.34 sendMsg; // Local message variable with
                        // name sendMsg, identifier 34,
                        // target controller CAN 2
                        sendMsg = this; // Copy all data and attributes
                        // of received message (this)
                        // to message to be transmitted
                        sendMsg.byte(4) = 0; // Change byte 4,
                        // always enter 0
                        output(sendMsg); // Transmit message
            }
 React to Keyboard Events

With on key procedures you can execute certain actions by key press. 

            on key 'a'                    React to press of .a. key
            on key ' ‘                     React to press of spacebar
            on key 0x20                React to press of spacebar
            on key F1                   React to press of F1 key
            on key ctrlF12                        React to press of Ctrl-F12
            on key PageUp          React to press of Page Up
            on key Home              React to press of Home
            on key *                      React to any key press
The code for a key press can either be input as a character, number or a predefined
name for a function key.

 Example of React to Keyboard Events

variables {
int counter = 0;
}
on key 'a' {
write("A total of %d messages 0x1A1 counted",counter);
}
on message 0x1A1 {
counter++;
output(this); // Only in the evaluation branch
}
on message * {
output(this); // Only in the evaluation branch !!!
}
 React to Changes in Values of Environment Variables
The “on envVar” event is caused by the value of an environmental variable
changing. (Note:Remember that environmental variables are only enabled in
CANoe.) The “this” keyword is used in conjunction with the getValue() function to
access the value of the environmental variable. For

 example:
            on envVar Switch {
                        int val;
                        val = getValue(this);
                        // Read value of Switch into val
            }
 React to Time Events
CAPL allows you to create timers for seconds (Timer) or milliseconds (msTimer).
After thesetimers have been set and expire, the corresponding “on timer” event
procedure is executed.
Thisfacility can be used to create a cyclic event if you reset the timer at the end of
the timer event procedure. Timers can also be used to respond to an event after a
delay.
The setTimer() function takes two parameters, the name of the timer and the length
of time to setthe timer. The length of time parameter has different units depending
on what kind of timer youare using. For a Timer, the units are seconds; for an
msTimer, the units are milliseconds.
Themaximum values are 1799 seconds and 65,535 milliseconds, respectively. The
cancelTimer()function can be called on a timer before it has expired to prevent the
timer event from triggering.Calling the cancelTimer() function has no effect if the
timer is not set or has already expired.

 Example for Time Events

msTimer myTimer; // Define millisecond timer
message 100 msg; // Define message to be transmitted
...
on key 'a' { // React to key press of 'a'...
setTimer(myTimer,20); // ... Set timer to 20 ms
}
...
on timer myTimer { // Send message after timer...
output(msg); // ... has elapsed
}
 React to System Events

The preStart, start, and stopMeasurement events are used to perform actions
before, at the start of, and after CANalyzer or CANoe measurements. If they are
defined, each is called once permeasurement. When the “Go” button is pressed in
CANalyzer or CANoe, the preStart event procedure is executed (if one exists).
You use this procedure to read data from files, initializevariables, or write to the
Write window. Other actions, such as outputting a message onto thebus, are not
available in the preStart event. Generally, actions that are invalid in the preStart
event procedure can be moved to the start event procedure.
After the preStart event procedure has completed executing, the start event
procedure is executed (if one exists). The start event procedure can be used to
initialize environmental variables, set timers, and output messages onto the bus.
The measurement is also started at this time.
 React to System Events

When you press the Stop button in CANalyzer or CANoe, the stopMeasurement
event procedure is executed (if one exists). You can use this procedure to print
statistics in the Write window, output messages onto the bus, or write to a log file.
After this event has finished executing, the measurement is stopped.
 React to CAN Controller Events

The  event  procedures  on errorActive,  on errrorPassive,  on warningLimit and on

busOff are called during a state transition or in response  to a change in the CAN
controller's error counter. Use these procedures to monitor  the error counter (e.g.
output a warning), to terminate the measurement if necessary,  or to execute a reset
after a transition to the Bus-Off state.
The  CAN  controller's  error  counters  can  be  accessed  within  the  CAN 
controller's  event procedures using the key word this:

 React to CAN Controller Events

on errorPassive {
...
write("CAN Controller ist in errorPassive")
write(" errorCountTX = %d", this.errorCountTX);
write(" errorCountRX = %d", this.errorCountRX);
};

 Expressions in CAPL

CAPL syntax  is based on the C programming language. The following

expressions  are permitted as they are in C:

· Instruction blocks: { ... }

· if { ... } and if {...} else { ... }
· switch, case, default
· for.., while.., do..while loops
· continue and break
· return
· ?: expression

 The Key Word this

The key word this is used to refer to the the data structure of an object within an
event procedure for receiving a CAN object or environment variable. For example,
the following accesses the first data byte of message 100 which is just  being
received: 
            on message 100 {
            byte byte_0;
            byte_0 = this.byte(0);
            ...
            }

 Event Message Transmission

            When information only needs to be transferred on an event basis, the event
message is used.
            This sample program uses the pressing of the ‘b’ key on the PC keyboard to
initiate a single CAN message transmission.
            variables
            {
                        message 0x555 msg1 = {dlc=1};
            }
            on key ‘b’
            {
                        msg1.byte(0)=0xAA;
                        output(msg1);
            }

 Periodic Message Transmission

When information requires transferring on a repetitive basis, the periodic message

is used.
variables
{
message 0x555 msg1 = {dlc=1};
mstimer timer1; // define timer1
}
on start
{
setTimer(timer1,100); // initialize timer to 100 msec
}
on timer timer1
{
setTimer(timer1,100); // reset timer
msg1.byte(0)=msg1.byte(0)+1; // change the data
output(msg1); // output message
}
 Conditionally Periodic Message Transmission

            When information requires transferring on a repetitive basis only when a

certain set of conditions is true, the conditionally periodic message is used.
on timer timerA
{
if(conditionA == 1) // if condition is still
true
{
setTimer(timerA,200); // then continue timer
}
msgA.byte(0)=msgA.byte(0)-1; // change the data
output(msgA); // output message
}

 Handling of Run-Time Errors

A number of run-time errors are monitored in CAPL:

· Division by zero
· Exceeding upper or lower array limits
· Exceeding upper or lower offsets in the data fields of messages
· Stack overflow when CAPL subroutines are called
If a run-time error is detected, the instrinsic function runError() is called. This out-
puts a message to the Write window containing the name of the CAPL program,
the
error type and an error index. The location of the particular CAPL source text
which
caused the error is found with the help of the error index. The measurement is
termi-
nated after output of the message.
The function runError() can also be called directly by the user to generate asser-
tions.
 
 Browser for Creating and Compiling CAPL Programs

Application Uses for CAPL

Create a black box to simulate the rest of the network.
Create a module simulator.
Simulate event messages, periodic messages, or conditionally repetitive messages
Application Uses for CAPL
Simulate human events like button presses using the PC keyboard
Simulate timed node or network events
Create a functional gateway between to different CAN networks.
CAPL Programming.