Introduction

# Hello, CAN!

Let's start with a simple example.

#include <canlib.h>
#include <stdio.h>
void main(void)
{
canHandle hnd;
canInitializeLibrary();
hnd = canOpenChannel(0, canOPEN_EXCLUSIVE);
if (hnd < 0) {
char msg[64];
canGetErrorText((canStatus)hnd, msg, sizeof(msg));
fprintf(stderr, "canOpenChannel failed (%s)\n", msg);
exit(1);
}
canSetBusParams(hnd, canBITRATE_250K, 0, 0, 0, 0, 0);
canSetBusOutputControl(hnd, canDRIVER_NORMAL);
canBusOn(hnd);
canWrite(hnd, 123, "HELLO!", 6, 0);
canWriteSync(hnd, 500);
canBusOff(hnd);
canClose(hnd);
}

What does it do?

1. The CANlib library is initialized by a call to canInitializeLibrary().
2. A channel to a CAN circuit is opened. In this case we open channel 0 which should be the first channel on the CAN interface. canOPEN_EXCLUSIVE means we don't want to share this channel with any other currently executing program.
3. The CAN bus bit rate is set 250 kBit/s, using a set of predefined bus parameters.
4. The CAN bus driver type is set.
5. The CAN chip is activated.
6. A message with (11-bit) CAN id = 123, length 6 and contents (decimal) 72, 69, 76, 76, 79, 31 is transmitted.
7. Wait until the message is sent or at most 500 ms.
8. Inactivate the CAN chip.
9. Close the channel.

What does it not do? Almost all error checking is omitted for brevity.

# Programmer's Overview

The CANlib API consists exclusively of functions. Most of the functions return a status code of type canStatus, which is a negative number if the call failed and canOK (zero) if the call succeeded.

Several functions accept pointer arguments. In most cases where an argument is a pointer, NULL can be passed.

The first call to the library must be a call to canInitializeLibrary(). This function will initialize the library.

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.

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. This is usually caused by a hardware or setup problem. Please refer to the troubleshooting guide if this occurs.

Next, suitable bus parameters should be set. This is done by a call to canSetBusParams(). CANlib provides several default parameter settings for the most common bus speeds (for example, 1M, 500k, 250k and 125k).

When this is done, we can safely go on-bus by calling canBusOn().

You transmit messages by calling canWrite(). Received messages are buffered by CANlib and can be read by calling canRead() or any of its relatives. If you want to have a notification when a CAN message arrives; this is done by calling canSetNotify.

You can temporarily take the circuit off-bus by calling canBusOff(). Final circuit cleanup is done by calling canClose().

# Redistributable Files in CANlib SDK

You may use and distribute the source code found in the SAMPLES directory in your own applications without restrictions.