 |
|
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.
No special canOPEN_xxx modifier flag is needed in the flags argument to canOpenChannel() when opening a channel in CAN mode.
Example. This example opens channel 0 for exclusive usage by this application.
When opening a channel as CAN, use canSetBusParamsTq() to specify bus parameters. Instructions and examples are found below.
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().
Example. This example opens channel 0 in CAN FD mode for exclusive usage by this application.
When opening a channel as CAN FD, use canSetBusParamsFdTq() to specify bus parameters. Instructions and examples are found below.
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.
Channel specific information and capabilities can be obtained by a call to canGetHandleData() or canGetChannelData(). What information to receive from the channel is specified by passing an argument of type canCHANNELDATA_xxx.
Example. Make a query for the device clock frequency.
Example. Print the upper and lower bit timing limits for a device associated with a specific CAN channel.
Obtain channel capabilities by passing argument canCHANNELDATA_CHANNEL_CAP and extended capabilities using flag canCHANNELDATA_CHANNEL_CAP_EX. Support for specific capabilities are tested by a bitwise AND operation with corresponding capability flags canCHANNEL_CAP_xxx, and canCHANNEL_CAP_EX_xxx.
Example. Check if channel has support for CAN FD, and setting bus speed and bit timing parameters using canSetBusParamsTq().
More examples of how to check capabilities can be found in example/c/channeldata.c
After opening a channel in classic CAN mode (see Open as CAN), the bus speed can be set either by manually specifying bit timing parameters, or by using predefined bitrate constants.
Use canSetBusParamsTq() to set the bit timing parameters on the CAN bus. Bit timing parameters are packaged in a struct kvBusParamsTq, note that the synchronization segment is excluded as it is always one time quantum long.
Example. To set the bus speed to 500 kbit/s on a CAN device with an 80 MHz oscillator:
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.
If uncertain how to calculate bit timing parameters, appropriate values can be acquired using the Bit Timing Calculator for CAN FD. Note that in classic CAN mode, only the nominal bus parameters are of concern when using the Bus Bit Timing Calculator.
For users that not are interested in specifying individual bit timing parameters, CANlib also provides a set of default parameter settings for the most common bus speeds through the canBITRATE_xxx constants. To set the bus speed using predefined bit rates, use canSetBusParams() with a canBITRATE_xxx constant as the second argument, and all trailing arguments set to zero.
Example. Setting the bus speed to 500 kbit/s:
Available predefined bitrate constants with corresponding bit timing parameters for a CAN device with an 80 MHz oscillator. [1]
| tq | phase1 | phase2 | sjw | prop | prescaler | Sample point | Bitrate | |
|---|---|---|---|---|---|---|---|---|
| canBITRATE_10K | 16 | 4 | 4 | 1 | 7 | 500 | 75% | 10 kbit/s |
| canBITRATE_50K | 16 | 4 | 4 | 1 | 7 | 100 | 75% | 50 kbit/s |
| canBITRATE_62K | 16 | 4 | 4 | 1 | 7 | 80 | 75% | 62 kbit/s |
| canBITRATE_83K | 8 | 2 | 2 | 2 | 3 | 120 | 75% | 83 kbit/s |
| canBITRATE_100K | 16 | 4 | 4 | 1 | 7 | 50 | 75% | 100 kbit/s |
| canBITRATE_125K | 16 | 4 | 4 | 1 | 7 | 40 | 75% | 125 kbit/s |
| canBITRATE_250K | 8 | 2 | 2 | 1 | 3 | 40 | 75% | 250 kbit/s |
| canBITRATE_500K | 8 | 2 | 2 | 1 | 3 | 20 | 75% | 500 kbit/s |
| canBITRATE_1M | 8 | 2 | 2 | 1 | 3 | 10 | 75% | 1 Mbit/s |
For bus speeds other than the predefined canBITRATE_xxx constants, bit timing parameters have to be specified manually.
After opening a channel in CAN FD mode (see Open as CAN FD), the bus speed can be set either by specifying bit timing parameters, or by using predefined bitrate constants.
Use canSetBusParamsFdTq() to set the bit timing parameters on the CAN bus in CAN FD mode. Bit timing parameters for both the arbitration and data phases need to be set using two separate kvBusParamsTq structs.
Example. Set the arbitration bitrate to 500 kbit/s and the data phase bitrate to 1000 kbit/s, with sampling points at 80% on a device with an 80 MHz oscillator.
If uncertain how to calculate bit timing parameters, appropriate values can be acquired using the Bit Timing Calculator for CAN FD
For users that are not interested in specifying individual bit timing parameters, CANlib provides a set of default parameter settings for the most common bus speeds through the canFD_BITRATE_xxx constants. Use canSetBusParams() to set the arbitration phase bus speed, and canSetBusParamsFd() to set the data phase bus speed.
Example. Set the arbitration phase bitrate to 500 kbit/s, with sampling point at 80% and the data phase bitrate to 1000 kbit/s, with sampling point at 80%.
Available predefined bitrate constants with corresponding bit timing parameters for a CAN FD device with an 80 MHz oscillator. [1]
| tq | phase1 | phase2 | sjw | prop | prescaler | Sample point | Bitrate | |
|---|---|---|---|---|---|---|---|---|
| canFD_BITRATE_500K_80P | 40 | 8 | 8 | 8 | 23 | 4 | 80% | 500 kbt/s |
| canFD_BITRATE_1M_80P | 40 | 8 | 8 | 8 | 23 | 2 | 80% | 1 Mbit/s |
| canFD_BITRATE_2M_80P | 20 | 8 | 4 | 4 | 7 | 2 | 80% | 2 Mbit/s |
| canFD_BITRATE_2M_60P | 20 | 8 | 8 | 4 | 3 | 2 | 60% | 2 Mbit/s |
| canFD_BITRATE_4M_80P | 10 | 7 | 2 | 2 | 0 | 2 | 80% | 4 Mbit/s |
| canFD_BITRATE_8M_80P | 10 | 7 | 2 | 1 | 0 | 1 | 80% | 8 Mbit/s |
| canFD_BITRATE_8M_70P | 10 | 6 | 3 | 1 | 0 | 1 | 70% | 8 Mbit/s |
| canFD_BITRATE_8M_60P | 5 | 2 | 2 | 1 | 0 | 2 | 60% | 8 Mbit/s |
For bus speeds other than the predefined canFD_BITRATE_xxx constants, bit timing parameters have to be specified manually.
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.
canDRIVER_NORMAL is set by default.
See how-to/c/openChannels.c for code sample.
The following functions are still supported in canlib.
canSetBusParams() can be used to set CAN bus parameters, including bitrate, the position of the sampling point etc, they are also described in most CAN controller data sheets. Depending on device and installed firmware, the requested parameters may be subject to scaling in order to accommodate device specific restrictions. As such, reading back bus parameters using canGetBusParams() can return bus parameter settings different than the ones supplied. Note however, that a successful call to canSetBusParams() will always result in the requested bit rate being set on the bus, along with bus parameters that for all intents and purposes are equivalent to the ones requested.
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.
Example. Set the speed to 111111 kbit/s, the sampling point to 75%, the SJW to 2 and the number of samples to 1:
For full bit timing control, use canSetBusParamsTq() instead.
After a channel has been opened in CAN FD mode, canSetBusParams() and canSetBusParamsFd() can be used to set the arbitration and data phase bitrates respectively. Depending on device and installed firmware, the requested parameters may be subject to scaling in order to accommodate device specific restrictions. As such, reading back bus parameters using canGetBusParamsFd() can return bus parameter settings different than the ones supplied. Note however, that a successful call to canSetBusParamsFd() will always result in the requested bit rate being set on the bus, along with bus parameters that for all intents and purposes are equivalent to the ones requested.
Example. Set the nominal bitrate to 500 kbit/s and the data phase bitrate to 1000 kbit/s, with sampling points at 80%.
For full bit timing control, use canSetBusParamsFdTq() instead.
[1] See Check Channel Capabilities for information on clock frequency.