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 and double),

    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 millisec-onds) serve to generate time events. Timer variables are not automatically initialized at  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 EngineData defined 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,     

     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 Procedures
Receipt of a CAN message	on message{}
Press of a key	on key{}
Initialization of measurement (before measurement start)	on prestart{}
Measurement start	on start{}
End of measurement	on stopMeasurement{}
CAN controller goes to ErrorActive	on errorActive{}
CAN controller goes to Error Passive	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.