Vector CAPL Tutorial

Micael Coutinho, • vectortoolingcapl
Back

Vector uses the CAPL programming language for automation and interaction with ECU's via the communication bus. Kickstart your CAPL knowledge here

If you are working with Vector tools, it is imperial to learn about CAPL (Communication Access Programming Language) and CASL (Calculation And Scripting Language), depending on the app you are dealing with. For CANoe and CANalyser, CAPL is the language used, whereas for CANape, one has to use CASL. Why they are both different? Ask Vector. Maybe because the apps themselves provide different levels of interaction. One can consider CANoe and CANalyser a lower level language, where you can actually see the PDU's coming through. So, it you are looking to automated testing, I would choose the one where you can interact on a lower level.

Before continuing with CAPL, let's see what we can take from it. It takes part of the CANoe interaction layer (CANoeIL), and allows you to access the bus in a signal-oriented way, which means you can send and parse received messages and even generate output signals beyond the communication bus (if you have the right hardware, of course). This allows you to create powerful testing apps, connected to a user inteface that can be controlled by someone who does not necessarily need to dominate the ECU internals, or even create automated tests, which can be used along with CI/CD (Continuous Integration / Continuous Development) tools, to generate reports and validate the ECU behavior, testing every nook and cranny of your code, providing you with a very mature and confidence-inspiring Software in the end.

Now that we got out of the way, let's play around with CAPL. The language itself is inspired by C (since you are the target user, you should be very familiar with C, so that's a plus, plus), although it diverges a bit, being event driven, not interrupt driven. It also makes use of the CANoe resources, providing easy integration with the system variables within your configuration, diagnostics, and even the signals described in your .dbc file. To develop CAPL, you are also gifted with an IDE (CAPL Browser), which I do not hate, but it would be nicer to work in VSCode. Just do not mix them at the same time. Bad things can happen. We are not going to use the IDE in our examples, as we want you to be able to use the examples we provide as your starting point. Although we encourage you to use it, as there are not very good extensions for it in other IDE's and it provides you autocomplete, and easier navigation.

To create a CAPL node, you go to the simulation setup tab, and select Add > Insert CAPL Test Module. You will end up with a block just like in the image below:

How to insert a CAPL Test Module { w: 1350, h: 749 }

How to insert a CAPL Test Module

After creating the node, you can right click on it and configure it. Some useful options are the script placement, when it starts (immediately after you start the simulation, or on a specific keyboard key or a CANoe system variable), generate a test report or the buses you want to use inside your CAPL script. Keep in mind, the configuration can change according to the version.

When you create and open the script, you are gifted with the following code snippet:

/*@!Encoding:1252*/
includes
{
  
}

variables
{
  
}

The includes scope allows you to add other files, as you would normally do in other languages, so that your code does not look like a spaghetti mess. In the variables scope, you can declare variables, messages and timers, among other things. Some examples are:

You can learn more about this and other particularities on CANoe's CAPL Browser by clicking on the blue interrogation symbol on the top right corner or pressing F1. This will open the surprisingly useful help.

Now, to finalize, let's dig through an example that just sends a cyclic message according to a system variable declared on the CANoe environment:

/*@!Encoding:1252*/
includes
{ 
  #include "math.can"
}

variables
{
  message 0x100 TxMessage;
  msTimer cyclic_timer;
  byte received_data = 0;
}

byte myFunction(byte in)   // how to declare a function
{
  return (in + 5);
}

on start        // simulation startup button handler
{
  setTimer(cyclic_timer, 100);  // starting the timer
}

on message 0x101    // message event handler
{
  byte result;    // local variables
  result = this.byte(0);   // how to read message contents
  myFunction(result);   // how to use a function
  received_data++;    // just because we love C
}

on timer cyclic_timer   // timer event handler
{
  TxMessage.byte(0) = (byte)(@sysvars::mySysvar & 0x0C);    // access message bytes. Bitwise operations and type castings are allowed
  TxMessage.byte(1) = (byte)(@sysvars::mySysvar >> 8);
  TxMessage.byte(2) = (byte)(@sysvars::mySysvar >> 16);
  TxMessage.byte(3) = (byte)(@sysvars::mySysvar >> 24);
  
  output(TxMessage);    // output message in the bus
  write("First byte received: %x", TxMessage.byte(0));      // how to print to the simulation console
  
  setTimer(cyclic_timer, 100);  // timer needs to be reset
}

If we go section by section:

As a side note, the other constructs from C are available, such as if clauses, switch cases, for and wrile loops. Just be careful not to create abusive loops. CAPL does not enjoy it.

Lastly, we hope this introduction to CAPL helps you ease into it. As you are seeing here, it's a quite useful skill to dominate and there is also high demand for it. We will build up on this article, with more CANoe and CAPL tutorials, so we hope you stick around to learn more! We also left a handbook related to CAPL, which is probably the best free resource to learn CAPL, other than the help button on CANoe. It has certainly helped us.

Author: Micael Coutinho (opens in a new tab)

References:

© AutosarToday —@LinkedIn