Initialization

Library Initialization

Calling canInitializeLibrary() initializes the CANlib library. It is sufficient to call this routine once. Calling it more than once will have no effect.

Library Deinitialization and Cleanup

Strictly speaking it is not necessary to clean up anything before terminating the application. If the application quits unexpectedly, the device driver will ensure the CAN controller is deactivated and the driver will also ensure the firmware (if any) is left in a consistent state.

To deinitialize the library in an orderly fashion you may want to call canWriteSync() with a short timeout for each open handle before closing them with canClose(), to ensure the transmit queues are empty.

If you want to reinitialize the library from scratch in an application that already has initialized the library, call canUnloadLibrary(). You can then start afresh by calling canInitializeLibrary() again.

Chips and Channels

A CAN interface card often have more than one CAN chip. You allocate a handle to a certain CAN chip by calling canOpenChannel(). This routine takes two arguments, the first of which is the number of the desired channel. The channel numbering is dependent on the hardware you are using.

Note
If you have e.g. a LAPcan, the channels are numbered 0 and 1. If you have a USBcan Professional, the channels are numbered 0 and 1 according to the markings on the cables. Please refer to the hardware documentation.

You can enumerate the CAN channels in the system using canGetChannelData(). First call canGetNumberOfChannels() to get the number of channels in the system. Then call canGetChannelData() for channel numbers 0, 1, 2,…, n-1 where n is the number returned by canGetNumberOfChannels().

Two or more applications can share the same CAN controller. You can, for example, have one application send messages on the bus and another application that just monitors the bus. If this is not desired (for performance or other reasons) you can open an exclusive handle to a chip. This means that no other application can open a handle to the same chip. Do this by passing the canOPEN_EXCLUSIVE flag in the flags argument to canOpenChannel().

Note
Never try to use a handle where a channel number is required, or vice versa. It might or might not succeed (because both handles and channel numbers are integers) but the result is not relibable and the code might break with a future release of the drivers.

Bit Rate and Other Bus Parameters

The bus parameters include the bit rate, the position of the sampling point etc. For a detailed discussion of these parameters, refer to our web site, http://www.kvaser.com; they are also described in most CAN controller data sheets.

Use canSetBusParams to set the bus parameters. CANlib provides a few default set of parameters for the most common bus speeds; you can specify any of the canBITRATE_xxx constants (defined in canlib.h) in the call to canSetBusParams and set the other parameters to 0. Here's a list of the canBITRATE_xxx constants that are currently defined.

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

stat = canSetBusParams(hnd, canBITRATE_500K, 0, 0, 0, 0, 0);

To set a bit rate that is not predefined, you have to calculate the appropriate bus parameters yourself. See the on-line help for a detailed explanation of the different parameters you can pass to canSetBusParams.

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);

If you feel more comfortable to use the almost-standard way of specifying the bus parameters using the register layout of the 82c200 CAN controller, you can call canSetBusParamsC200 instead.

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

stat = canSetBusParamsC200(hnd, 0x5D, 0x05);

This also sets the sampling point to 87.5% of a bit, and the SJW to 2 quanta.

CAN Driver Modes

Driver mode
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. This might be handy for e.g. automatic bit rate detection.

canDRIVER_NORMAL is the default, so your code doesn't have to set it explicitly.

Line mode
Certain CAN transceiver types support line modes. Most important, the low-speed transceivers (82c252/TJA1053/TJA1054 and so on) support sleep and suspend modes, and the single-wire CAN transceivers (AU5790 etc.) support a highspeed mode. Use canSetDriverMode() with canTRANSCEIVER_LINEMODE_xxx to set the line mode.

Resnet mode
Certain rarely seen custom-specific transceivers also support a resnet mode. Use canSetDriverMode() with canTRANSCEIVER_RESNET_xxx to set this mode.