t Programming

Table of Contents

Overview

The Kvaser t programming language is event oriented and modeled after C. It can be used to customize the behavior of Kvaser t capable devices. devices.

A t program is invoked via hooks, which are entry points that are executed at the occurrence of certain events. These events can be, for example, the arrival of specific CAN messages, timer expiration, or external input.

Here we will describe how to interact with t programs on a Kvaser device (i.e. loading, starting, stopping) For a complete reference to the t language, see the Kvaser t Programming Language available from www.kvaser.com/downloads.

Load and Unload Script

The first step is to compile your t program into a .txe file, see the Kvaser t Programming Language. A compiled .txe file may be examined using kvScriptTxeGetData().

Before starting a t program you need to load it into an available "slot". Some Kvaser devices have multiple slots, and are therefore capable of running multiple programs simultaneously.

To load a script located on the host PC, use kvScriptLoadFile(). The canHandle argument is used to determine what channel is set as the default channel for the loaded script. If your canHandle was opened via a device's second channel, the default channel number will be set to 1 (the numbering of channel on the card starts from 0).

To load a script located on the device, use kvScriptLoadFileOnDevice(). To copy arbitrary files to and from the the device, use kvFileCopyToDevice() and kvFileCopyFromDevice() respectively.

Example. The following code fragment shows how to load the compiled script "script0.txe" from PC and "script3.txe" from the SD card, using the channel number "hnd" was opened with as the default channel.

canStatus stat;
CanHandle hnd;
...
// Load a script that is stored locally (on SD) into script slot 0
stat = kvScriptLoadFileOnDevice(hnd, 0, "script0.txe");
if (stat < 0) {
printf("Load failed (0), status == %d\n", stat);
}
// Load another script stored on the host (PC) into script slot 3
stat = kvScriptLoadFile(hnd, 3, "script3.txe");
if (stat < 0) {
printf("Load on device failed (3), status == %d\n", stat);
}

To unload a stopped script, use kvScriptUnload().

You may use kvFileGetCount(), and kvFileGetName() to examine files located on the Kvaser device, and kvFileDelete() to delete a specific file.

Note
Not all Kvaser devices support storing t programs and other files locally on the device (i.e. USBcan Pro 2xHS v2). Please refer to your device's User Guide for more information. All User Guides may be downloaded from www.kvaser.com/downloads

Start and Stop script

To start a previously loaded t program, use kvScriptStart(). You may stop a running script using kvScriptStop(). To examine the status of a slot (i.e. if the slot is free or have a program loaded or running), use kvScriptStatus().

Example. Starting and stopping scripts loaded in slot 0 and 3.

// Start script in slot 0
stat = kvScriptStart(hnd, 0);
if (stat < 0) {
printf("Start failed (0), status == %d\n", stat);
}
// Start script in slot 3
stat = kvScriptStart(hnd, 3);
if (stat < 0) {
printf("Start failed (3), status == %d\n", stat);
}
...
// Try to stop script in slot 3
stat = kvScriptStop(hnd, 3, kvSCRIPT_STOP_NORMAL);
if (stat < 0) {
printf("Stop (3) failed, status == %d\n", stat);
// For some reason this failed (script is busy?) so we request it to stop.
// Note that this is an request and that the script might still be running
// when this call returns.
stat = kvScriptStop(hnd, 3, kvSCRIPT_STOP_FORCED);
if (stat < 0) {
printf("Forced stop failed (3), status == %d\n", stat);
}
Sleep(100); // make sure it has stopped.
}
...

Environment Variable

To communicate between the PC and your t program, you can use t Environment Variables (Envvar). The first step is to get a handle to your Envvar using kvScriptEnvvarOpen().

Depending of the type of the Envvar, you may now examine the value using kvScriptEnvvarGetInt(), kvScriptEnvvarGetFloat() and kvScriptEnvvarGetData(). The size of the "Data" Envvar is set by the user but can be max kvScriptGetMaxEnvvarSize() bytes.

To change the value of the Envvar, use kvScriptEnvvarSetInt(), kvScriptEnvvarSetFloat() and kvScriptEnvvarSetData() respectively.

Use kvScriptEnvvarClose() to free up memory when done handling the Envvar

Example. The following code fragment shows how to use environment variables, Envvars for communication between a PC and a script.

CanHandle hnd;
kvEnvHandle env_hnd;
canStatus stat;
int envvar_size;
int envvar_type;
int int_val = 0;
float float_val = 0;
char buffer_val[10] = {0,0,0,0,0,0,0,0,0,0};
...
// Open an int envvar called "ev1_int" and set its value to 55
env_hnd = kvScriptEnvvarOpen(hnd, "ev1_int", &envvar_type, &envvar_size);
if (env_hnd < 0) {
printf("Open failed, env_hnd = %d\n", env_hnd);
} else {
printf("envvar_size = %d, envvar_type = %d\n", envvar_size, envvar_type);
stat = kvScriptEnvvarSetInt(env_hnd, 55);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
// Read back the value of "ev1_int" and close.
stat = kvScriptEnvvarGetInt(env_hnd, &int_val);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
} else {
printf("int_val = %d\n", int_val);
}
stat = kvScriptEnvvarClose(env_hnd);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
}
// Open a float envvar called "ev1_float" and set its value to 55.55
env_hnd = kvScriptEnvvarOpen(hnd, "ev1_float", &envvar_type, &envvar_size);
if (env_hnd < 0) {
printf("Open failed, env_hnd = %d\n", env_hnd);
} else {
printf("envvar_size = %d, envvar_type = %d\n", envvar_size, envvar_type);
stat = kvScriptEnvvarSetFloat(env_hnd, (float)55.55);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
// Read back the value of "ev1_int" and close.
stat = kvScriptEnvvarGetFloat(env_hnd, &float_val);
if (stat < 0) {
printf("Failed, stat == %d\n", stat);
}
printf("float_val = %f\n", float_val);
stat = kvScriptEnvvarClose(env_hnd);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
}
// Open a buffer envvar called "ev1_buffer" and set its value to ""hello1234""
env_hnd = kvScriptEnvvarOpen(hnd, "ev1_float", &envvar_type, &envvar_size);
if (env_hnd < 0) {
printf("Open failed, env_hnd = %d\n", env_hnd);
} else {
printf("envvar_size = %d, envvar_type = %d\n", envvar_size, envvar_type);
// Set value, starting at index 0 in buffer and length 10
stat = kvScriptEnvvarSetData(env_hnd, "hello1234", 0, 10);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
// Read back the value of "ev1_buffer" and close.
stat = kvScriptEnvvarGetData(env_hnd, buffer_val, 0, 10);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
printf("buffer_val = %s\n", buffer_val);
stat = kvScriptEnvvarClose(env_hnd);
if (stat < 0) {
printf("Failed, stat = %d\n", stat);
}
}

Send Event

You may trigger the "on key" hook by sending the event kvEVENT_TYPE_KEY to a script using kvScriptSendEvent().

Example. The following code fragment shows how to send a key to a script.

CanHandle hnd;
canStatus stat;
int slot_number;
...
// Send key 'a' to scripts running in slot 0...3
for (slot_number = 0; slot_number < 4; slot_number++) {
stat = kvScriptSendEvent(hnd, slot_number, kvEVENT_TYPE_KEY, 'a', 0);
}