CAPL Language

Introduction to CAPL:

The CAPL or CAN Access Programming Language is one of the programming languages used in the Automotive field to test the multiple ECU by using the Vector-based testing tool Canalyzer/Canoe. The CAPL is based on the C-Programming language but it is the addition of features to support the CAN-based embedded system development.

Basically, we can say the CAPL is the event-driven programming language. The CAPL applications can be developed to respond to the different system events such as on start, on-message, keypress, on the timer, software timers, CAN-messages, CAN bus off states, etc. and then it will execute to the routine in an interrupt-like manner.

There are several CAN-based functions in CAPL for the purpose of diagnostic communication that will extensively be used in the preferred project for the UDS protocol communication between the test environment and the ECU during the software flashing process. There are two different file formats supported by CAPL as CIN- and CAN- files

CIN-CAN files: A CAN file is a non-executable file format used in CAPL, which can include the functions, constants, and variables that can be used in several different applications that are typically stored in CIN-files. This will enable the reuse of the commonly used variables and functions. The CIN-files are included in a CAN-file, which will then gain access to the functions and variables included in the CIN-files.

The original design intent behind CAPL (which is pronounced “apple”) was to meet the CAN-based distributed embedded system developer’s requirements including:

• Maximum control of all test and measurement operations.
• Maximum control of system or module simulation – CANoe- or CANalyzer-specific.
• Maximum support for one or more communication channels.
• Maximum event and message recording and playback control.
• Ability to interconnect to other PC applications.

Using CANalyzer or CANoe in combination with CAPL makes it possible to create custom tool applications with user-defined behavior. Potential applications are limited only by the imagination, available communication hardware limitations (if applicable), and the speed of the PC.

CAPL Evaluation Capability:

The CANalyzer or CANoe tool itself, without CAPL programs, is enough to execute simple measurement and analysis. With CAPL programs involved, measurement and analysis are greatly extended for CAN communication. One area that the tool cannot perform without CAPL is an analysis that involves timing. CAPL can make the analysis more efficient with the help of timers. CAPL can be used in an application to:

• Analyze specific messages or specific data.
• Analyze data traffic.
• Create and modify the tool’s measurement environment.
• Design a custom module tester.
• Create a black box to simulate the rest of the network.
• Create a module simulator.
• Create a custom module manufacturing tester.
• Create a custom module diagnostic or service tool.
• Create programs to perform customized analysis of network logging (playback) files.
• Create complex logging filters.
• Create a comprehensive message or data content generation tester for the module/network validation.
• Program a functional gateway between two different networks.
• Evaluate the module network software strategy by generating CAN error frames in simulation to see if modules are working properly.

CAPL Simulation Capability:

The situation often arises when developing a distributed application that a portion or part of the application is not available for testing. The system environment can be emulated with the help of the CAPL, for example, to simulate the data traffic of all remaining network nodes. For this reason, the CAPL can also be used to simulate:

• Node or system behavior using readable English instructions and values rather than hexadecimal values.
• Event messages, periodic messages, or conditionally repetitive messages.
• Human events like button presses on the PC keyboard.
• Timed node or network events.
• Multiple time events, each with its own programmable behavior.
• Normal operation, diagnostic operation, or manufacturing operation.
• Changes in physical parameters or symbolic values (for example, “ON”, “OFF”).
• Module and network faults to evaluate a limited operation strategy.
• Simple or complex functions (sin, cos).

Prerequisites for Using CAPL:

To use CAPL effectively you need the following:

• A CANalyzer or CANoe tool – the programmable version is required.
• An understanding of the CAPL Browser – where you write your CAPL program.
• A database tool – CANdb++ – to create your shared network data variables.
• CAPL programming knowledge – available in this book.
• A small amount of CAN communication knowledge.

For those students and engineers who do not have access to a real CANalyzer or CANoe, consider using the demo version of the tools (available from the Download Center at http://www.vector-cantech.com). Even without real communication hardware, the considerable experience can be gained using the demo version.

In addition, because CAPL is based on C, the user must be familiar with the C or C++ language. Users need not be familiar with the programming orientation, mechanics, and its libraries, but on the syntax, operators, expressions, and statements. Some common statements in C can also be found in the CAPL. For example, the C function printf() is known as the write() function in both CANalyzer and CANoe to output data to the write window. Both functions use exactly the same C/C++ formatting characters in the argument with the percent sign (%d for integers, %s for a string, and so on.).

How To Learn CAPL Programming?

CAPL represents the programmable portion of the CANoe and CANalyzer. Although there are significant differences between the two tools, both share a large set of features. For learning purposes, however, it is easier to learn CANalyzer first, as CANoe is built on the foundation of the CANalyzer. While both tools are valuable in the development of any distributed product or distributed embedded system architecture, CANoe possesses more powerful features than CANalyzer. In general, system and distributed product developers typically use the CANoe.

Difference between CANalyzer and CANoe?

The CANalyzer and CANoe tools were developed to meet the essential needs of the CAN-based module or system developer by combining a comprehensive set of measurement and simulation capabilities. Both CANalyzer and CANoe can interface to multiple CAN networks (or other common small area network protocols), and provide accurate time-stamped measurements for all communication transfers, including both acknowledged messages and communication errors. Recording and playback operations are standard. Users can record the messages from one system and e-mail them to another engineer for playback and analysis.

Both tools basically operate like a multi-channel oscilloscope, a multi-channel logic analyzer, and a custom alphanumeric display unit – all using an integrated database.

In addition, both tools are capable of creating any message generation pattern, much like a programmable function generator, with the complete control of all network data variables (or signals).

Basics Of CAPL Programming:

CAPL Keywords: Keywords cannot be used to name a variable or function. CAPL uses reserved keywords from the C programming language. Some common C keywords are: break, case, char, continue, default, do, double, else, float, for, if, int, long, return, switch, while.

CAPL Data Types: The basic data types supported by the CAPL are integer, character, and floating-point, as listed in Table 6. The message, timer, and msTimer are considered data types because they define a variable that symbolizes the kind of data they can store and operate. Unsigned variables can only have non-negative values, whereas signed variables can either be positive or negative.

How to declare CAPL Variables?

To allow variables to be read or changed in any part of a CAPL program, use global variable declarations in the Global Variables window of the CAPL Browser. Below is a list of some examples of declarations:

char Name = “prakash”;
int days_in_year = 365;
message wake-up xxx; // see Chapter 11 on using messages for more detail
timer one_second; // see Chapter 14 on using timers for more detail
int j, k = 2; // j = 0 implicitly
double x = 33.7;
char p;

Local Variable declaration in CAPL?

One important difference in the CAPL, when compared to C, is that local variables are always declared statically. This means that they are initialized only once – the first time the event procedure or user-defined function is executed. When variables enter the procedure, they assume the value they had at the end of the previous execution of the procedure.

void myFunc()
{
    byte value = 10; // static; called once
    write(“value = %d”, value);
    value = 35;
}

Creating a CAPL Program

To create a CAPL program, you need to use the dedicated browser in CANoe or CANalyzer. The browser allows you to access all the objects defined in the database (messages, signals, environment variables) as well as system variables. You can also use predefined functions provided by CAPL to perform various tasks.

To open the browser, select Edit -> Browser from the menu bar or press F9. You will see a window like this:

The browser window consists of three parts:

1. The left pane shows the tree view of all available objects in your configuration.
2. The middle pane shows the details of the selected object.
3. The right pane shows the editor where you can write your CAPL code.

To create a new CAPL program file (also called node), right-click on Simulation -> Node Layer -> Nodes and select New Node from the context menu. You will be prompted to enter a name for your node file. For example, let’s name it TestNode.capl.

After creating your node file, you will see it appear in the tree view under Nodes. You can double-click on it to open it in the editor.

A node file consists of four sections: variables, includes, timers and functions. Each section starts with its keyword followed by curly braces {}.

• Variables Section: Here you can declare global variables that are accessible throughout your program.
• Includes Section: Here you can include other files that contain definitions or declarations that you want to use in your program.
• Timers Section: Here you can declare timers that can be used to trigger functions after a specified time interval.
• Functions Section: Here you can define functions that implement your program logic.

Writing Your First CAPL Program

Let’s write a simple program that sends a message every second on CAN bus 1 and prints its contents on Write window 1. First, we need to declare a message variable and a timer variable in our variables section:

variables
{
message msg; // A message variable
msTimer sendTimer; // A millisecond timer variable
}

A message variable is used to store information about a message such as its identifier (ID), data length code (DLC) and data bytes. A msTimer variable is used to store information about a timer such as its name and duration.

Next, we need to include some files that contain predefined constants and functions that we want to use in our program:

includes
{
    #include "canoeapi.h" // Contains constants for bus types
    #include "canmsg.h" // Contains constants for message types
}

The canoeapi.h file contains constants for different bus types such as kCAN1 for CAN bus 1. The canmsg.h file contains constants for different message types such as kStandardMsg for standard messages.

Next, we need to define our timer function that will be executed when our timer expires:

timer sendTimer // Timer function declaration
{
    output(msg); // Send message on default bus (CAN bus 1)
    write("Sent message ID = %d DLC = %d Data = %X %X %X %X %X %X %X %X", msg.id,
    msg.dlc,
    msg.byte(0),
    msg.byte(1),
    msg.byte(2),
    msg.byte(3),
    msg.byte(4),
    msg.byte(5),
    msg.byte(6),
    msg.byte(7)); // Print message contents on Write window 1
    setTimer(this.timer(),1000); // Restart timer with one second interval
}

How to send a Message in CAPL?

Ex:
File Simparameter.CIN ::
variables
{
    int _simpar_granularity_ms = 10;
}

File Door_Right.CAN ::
includes
{
    #include “Simparameter.CIN”
}
variables
{
    msTimer cyclicTimer;
}
on start
{
    setTimer(cyclicTimer, simpar_granularity_ms);
}
on Timer cyclicTimer
{
    setTimer(cyclicTimer, simpar_granularity_ms);
}