CAPL Programming Examples

In this chapter, we will show examples of common programming tasks with CAPL. It is a good
idea to skim through the examples in this section to become familiar with what it contains so you
can refer to it later as a reference. Some examples build on examples and ideas from other
sections, so you might need to refer to more than one section to get a complete answer to your

5.1 Sending an Event Message
You can send a message (or multiple messages) on any event, for example, a keypress, the
reception of another message, the reception of an error frame, or a timer expiring. Sending an
event message involves creating an event procedure, declaring a message to send, and sending
the message in the event procedure.
The message can be declared as a global variable so that it can be accessed in any event
procedure. As shown in the message object section, you can declare a message’s structure in
your program or you can use an associated database. In this example, we will declare one of
each in the Global Variables window (upper right corner).
variables {
message EngineData msg1; // Defined in database
message 0x101x msg2; // Extended message 101 (hex)
Now, to send a message, we only need to put one of these lines into an event procedure:
Of course, we can also add data to the message before we send it. The EngineData message
has signals defined in the database, but the other message does not. Therefore, we have to use
two different methods to add data to the messages.
msg1.EngSpeed.phys = 1000;
msg1.EngTemp.phys = 150;
msg1.IdleRunning = 1;
msg2.DLC = 4; // Allocate 4 data bytes in msg2
msg2.word(0) = 0x165; // First word is 165 hex
msg2.word(1) = 747; // Second word is 747 decimal
CAPL Programming Examples
CAPL Reference Manual 153
Notice that the phys modifier was used on msg1’s signals, because they had conversion formulae
defined in the associated database. The phys modifier was not used on the IdleRunning signal
because it is a one-bit signal with no conversion formula defined.
Statements like these (assigning data to messages and using output() to send them) can be
used in most event procedures, such as:
on key someKey { . . . }
on envVar someVar { . . . }
on message someMsg { . . . }
on errorFrame { . . . }
on Timer someTimer { . . . }
on start { . . . }
To define an event procedure, you must first select the corresponding category in the Event
Types window (upper left corner). Then, right-click in the Event Procedures window and select
New from the menu. Refer to the chart in the Events section of the manual for a list of event
types and corresponding event procedures.

5.2 Sending a Periodic Message
Sending a periodic message requires setting up a timer and using the timer event procedure to
send the message and reset the timer.
First, declare a timer in the Global Variables window (upper right corner). You can use a Timer
object for a seconds-based timer or an msTimer object for a milliseconds-based timer. You
should also define a global variable to contain the period for the timer. If you need to change the
timer’s period, it is much easier if you only need to change the value in one location in your code.
We will also declare a message as a global variable, but like the timer period variable, this is not
necessary to declare globally.
variables {
. . .
msTimer periodicTimer; // Set up an ms-based timer
long timerPeriod = 100; // Period will be 100ms
// We can declare any kind of message we want
// to send, but for simplicity’s sake, we will
// just make one up with 1 byte of data.
message 101 msg = { dlc = 1 };
. . .
CAPL Programming Examples
CAPL Reference Manual 154
Next, we need to initialize the timer in the start event procedure. If you do not yet have a start
event, select System from the Event Types window (upper left corner). Then right-click in the
Event Procedures window (lower left corner) and select Start from the New submenu. You will
see the on start event procedure created in the Event Procedure window (lower right corner).
After you are in the on start event procedure, you should add a setTimer command to
initialize the timer for the first time. If you do not do this, the timer event never occurs. Also,
make sure to use the global variable containing the period (timerPeriod in this case) with the
setTimer() function instead of the actual value (100 in this case).
on start {
. . .
setTimer(periodicTimer, timerPeriod);
. . .
As soon as the timer is set, it is activated and begins to count down. When the count reaches
zero, the corresponding on timer event procedure is executed. We need to create this event
procedure now. In the Event Types window (upper left corner), select Timer. Then, right-click in
the Event Procedures window (lower left corner) and choose New. In the Procedure Editing
window (lower right corner), you will see that a skeletal event procedure has been created.
To write your own event procedure, first replace the <newTimer> string with the name of the
timer you have declared (periodicTimer in this case). Then, write the code to send the message
in the body of the procedure. Finally, add a setTimer function call at the end of the body of code.
on timer periodicTimer
// We can send out whatever data we want here.
msg.byte(0) = 6;
// Again, use the global variable to set the
// timer instead of a variable
setTimer(periodicTimer, timerPeriod);
CAPL Programming Examples

CAPL Reference Manual 155                                                      NEXT>>

1 comment:

  1. This is a smart blog. I mean it. You have so much knowledge about this issue, and so much passion. You also know how to make people rally behind it, obviously from the responses.