Open Channel

Once we have called canInitializeLibrary() to enumerate the connected Kvaser CAN devices, the next call is likely to be a call to canOpenChannel(), which returns a handle to a specific CAN circuit. This handle is then used to all subsequent calls to the library. The canOpenChannel() function takes two arguments, the first of which is the number of the desired channel, the second argument is modifier flags canOPEN_xxx.

canOpenChannel() may return several different error codes, one of which is canERR_NOTFOUND. This means that the channel specified in the first parameter was not found, or that the flags passed to canOpenChannel() is not applicable to the specified channel.

Open as CAN

No special canOPEN_xxx modifier flag is needed in the flags argument to canOpenChannel() when opening a channel in CAN mode.

hnd = canOpenChannel(channel_number, 0);

Example. This example opens channel 0 for exclusive usage by this application.

if (hnd < 0) {
printf("Open failed, stat=%d\n", hnd);
}

When opening a channel as CAN, use canSetBusParamsTq() to specify bus parameters. Instructions and examples are found below.

Open as CAN FD

To open a channel in CAN FD mode, either canOPEN_CAN_FD or canOPEN_CAN_FD_NONISO needs to be given in the flags argument to canOpenChannel().

hnd = canOpenChannel(channel_number, canOPEN_CAN_FD);

Example. This example opens channel 0 in CAN FD mode for exclusive usage by this application.

if (hnd < 0) {
printf("Open failed, stat=%d\n", hnd);
}

When opening a channel as CAN FD, use canSetBusParamsFdTq() to specify bus parameters. Instructions and examples are found below.

Close Channel

Closing a channel is done using canClose(). If no other handles are referencing the same CANlib channel, the channel is taken off bus. The handle can not be used for further references to the channel, so any variable containing this handle should be set to canINVALID_HANDLE.

canStatus stat = canClose(hnd);
if (stat < 0) {
printf("Close failed.");
}

Set CAN Bitrate

After opening a channel as CAN, use canSetBusParamsTq() to set CAN bus parameters. Bus parameters, including the total nominal bit time and individual phase segments in number of time quanta etc, must be packaged in a struct kvBusParamsTq. The synchronization segment is excluded as it is always one time quantum. Appropriate parameters can be calculated using the Bit Timing Calculator for CAN FD. Note that for classic CAN, only the nominal bus parameters are of concern when using the Bus Bit Timing Calculator. Device clock frequency and additional information can be obtained by a call to canGetChannelData(), with suitable arguments, e.g. canCHANNELDATA_CLOCK_INFO.

Example. To set the bus speed to 500 kbit/s on a CAN device with an 80 MHz oscillator:

kvBusParamsTq params = { 8, 2, 2, 1, 3, 20 };
stat = canSetBusParamsTq(hnd, params);
if (stat < 0) {
printf("canBusParams failed, status=%d\n", stat);
exit(1);
}

In the example a prescaler of 20 is used, resulting in each bit comprising of 160 time quanta (8 * 20). The nominal bus speed is given by 80*10^6/(20*8) = 500*10^3.

Parameter settings for the most common bus speeds are listed in the below table.

tqphase1phase2sjwpropprescalerSample pointName of Constant
10 kbit/s16441750075%canBITRATE_10K
50 kbit/s16441710075%canBITRATE_50K
62 kbit/s1644178075%canBITRATE_62K
83 kbit/s8222312075%canBITRATE_83K
100 kbit/s1644175075%canBITRATE_100K
125 kbit/s1644174075%canBITRATE_125K
250 kbit/s822134075%canBITRATE_250K
500 kbit/s822132075%canBITRATE_500K
1 Mbit/s822131075%canBITRATE_1M

Examples in the reference table are presented for a CAN device with an 80 MHz oscillator.

Set CAN FD Bitrate

After opening a channel in CAN FD mode (passing either canOPEN_CAN_FD or canOPEN_CAN_FD_NONISO to canOpenChannel()), parameters for both the arbitration and data phases need to be set, this is done by a call to canSetBusParamsFdTq(). Parameter settings for the arbitration and data phases are passed as individual kvBusParamsTq.

Example. Set the arbitration bitrate to 500 kbit/s and the data phase bitrate to 1000 kbit/s, with sampling point at 80% using an 80 MHz oscillator. Note that only prescaler values of 1 or 2 are valid as input for CAN FD. Also, identical prescaler values must be used for the arbitration and data bus parameter settings.

kvBusParamsTq paramsArbitration = { 80, 16, 16, 16, 47, 2 };
kvBusParamsTq paramsData = { 40, 31, 8, 8, 0, 2 };
stat = canSetBusParamsFdTq(hnd, paramsArbitration, paramsData);
if (stat < 0) {
printf("canBusParams failed, status=%d\n", stat);
exit(1);
}

Parameter settings for the most common CAN FD bus speeds are listed in the table below. For other desired CAN FD bitrates, the Bit Timing Calculator for CAN FD is available on the Kvaser web site.

Data phase parameter settings for common bus speeds

tqphase1phase2sjwpropprescalerSample pointName of Constant
500 kbit/s806316160280%canFD_BITRATE_500K_80P
1 Mbit/s4031880280%canFD_BITRATE_1M_80P
2 Mbit/s2015440280%canFD_BITRATE_2M_80P
4 Mbit/s107220280%canFD_BITRATE_4M_80P
8 Mbit/s52210260%canFD_BITRATE_8M_60P

Arbitration phase parameter settings for common bus speeds

tqphase1phase2sjwpropprescalerSample pointName of Constant
500 kbit/s8016161647280%canFD_BITRATE_500K_80P
1 Mbit/s4088823280%canFD_BITRATE_1M_80P

Examples in the reference tables are presented for a CAN device with an 80 MHz oscillator.

CAN Driver Modes

Use canSetBusOutputControl() to set the bus driver mode. This is usually set to canDRIVER_NORMAL to obtain the standard push-pull type of driver. Some controllers also support canDRIVER_SILENT which makes the controller receive only, not transmit anything, not even ACK bits. This might be handy for e.g. when listening to a CAN bus without interfering.

stat = canSetBusOutputControl(canDRIVER_SILENT);

canDRIVER_NORMAL is set by default.

Code Sample

See how-to/c/openChannels.c for code sample.

Legacy Functions

The following functions are still supported by canlib. It is, however, recomended to use later implementations instead, see referenced functions in the individual paragraphs.

Set CAN Bitrate

Use canSetBusParams() to set the CAN bus parameters. The bus parameters include the bit rate, the position of the sampling point etc, they are also described in most CAN controller data sheets. CANlib provides a few default set of parameters for the most common bus speeds through the canBITRATE_xxx constants. When using these constants in the call to canSetBusParams(), set the rest of the arguments to '0'.

Example. To set the bus speed to 500 kbit/s:

stat = canSetBusParams(hnd, canBITRATE_500K, 0, 0, 0, 0, 0);
if (stat < 0) {
printf("canBusParams failed, status=%d\n", stat);
exit(1);
}

To set a bit rate that is not predefined, you have to calculate the appropriate bus parameters yourself.

Example. Set the speed to 125 kbit/s, each bit comprising 8 (= 1 + 4 + 3) quanta, the sampling point occurs at 5/8 of a bit; SJW = 1; one sampling point.

stat = canSetBusParams(hnd, 125000, 4, 3, 1, 1, 0);

Example. Set the speed to 111111 kbit/s, the sampling point to 75%, the SJW to 2 and the number of samples to 1:

stat = canSetBusParams(hnd, 111111, 5, 2, 2, 1, 0);

Prefarably use canSetBusParamsTq() instead.

Set CAN FD Bitrate

In CAN FD we need to set both the arbitration/nominal bitrate, using canSetBusParams(), and the data phase bitrate, using canSetBusParamsFd(). CANlib provides a few default set of parameters for the most common CAN FD bus speeds through the canFD_BITRATE_xxx constants. When using these constants in the call to canSetBusParams() and canSetBusParamsFd(), set the rest of the arguments to '0'.

Example. Set the nominal bitrate to 500 kbit/s, with sampling point at 80% and the data phase bitrate to 1000 kbit/s, with sampling point at 80%.

stat1 = canSetBusParams(hnd, canFD_BITRATE_500K_80P, 0, 0, 0, 0, 0);
stat2 = canSetBusParamsFd(hnd, canFD_BITRATE_1M_80P, 0, 0, 0);

For more copmplex settings of CAN FD bitrates, use the Bit Timing Calculator for CAN FD available on the Kvaser web site.

Prefarably use canSetBusParamsFdTq() instead.