Kvaser Linux CANLIB: Welcome to Kvaser CANLIB!
Functions
LIN

Functions

void linInitializeLibrary (void)
 
void linUnloadLibrary (void)
 
LinStatus linGetTransceiverData (int channel, unsigned char eanNo[8], unsigned char serNo[8], int *ttype)
 
LinHandle linOpenChannel (int channel, int flags)
 
LinStatus linClose (LinHandle h)
 
LinStatus linGetFirmwareVersion (LinHandle h, unsigned char *bootVerMajor, unsigned char *bootVerMinor, unsigned char *bootVerBuild, unsigned char *appVerMajor, unsigned char *appVerMinor, unsigned char *appVerBuild)
 
LinStatus linGetChannelData (int channel, int item, void *buffer, size_t bufsize)
 
LinStatus linSetBitrate (LinHandle h, unsigned int bps)
 
LinStatus linBusOn (LinHandle h)
 
LinStatus linBusOff (LinHandle h)
 
unsigned long linReadTimer (LinHandle h)
 
LinStatus linWriteMessage (LinHandle h, unsigned int id, const void *msg, unsigned int dlc)
 
LinStatus linRequestMessage (LinHandle h, unsigned int id)
 
LinStatus linReadMessage (LinHandle h, unsigned int *id, void *msg, unsigned int *dlc, unsigned int *flags, LinMessageInfo *msgInfo)
 
LinStatus linReadMessageWait (LinHandle h, unsigned int *id, void *msg, unsigned int *dlc, unsigned int *flags, LinMessageInfo *msgInfo, unsigned long timeout)
 
LinStatus linUpdateMessage (LinHandle h, unsigned int id, const void *msg, unsigned int dlc)
 
LinStatus linSetupIllegalMessage (LinHandle h, unsigned int id, unsigned int cFlags, unsigned int delay)
 
LinStatus linSetupLIN (LinHandle h, unsigned int lFlags, unsigned int bps)
 
LinStatus linWriteWakeup (LinHandle h, unsigned int count, unsigned int interval)
 
LinStatus linClearMessage (LinHandle h, unsigned int id)
 
LinStatus linWriteSync (LinHandle h, unsigned long timeout)
 
LinStatus linGetCanHandle (LinHandle h, unsigned int *canHandle)
 

Detailed Description

Function Documentation

◆ linInitializeLibrary()

void linInitializeLibrary ( void  )

This function initializes the LIN library and must be called before any other LIN function is called. If this function isn't called, subsequent calls to the other LIN functions will return linERR_NOTINITIALIZED.

See also
linOpenChannel()

◆ linUnloadLibrary()

void linUnloadLibrary ( void  )

This function de-initializes the LIN library. After this function is called /ref linInitializeLibrary must be called before any other LIN function is called.

◆ linGetTransceiverData()

LinStatus linGetTransceiverData ( int  channel,
unsigned char  eanNo[8],
unsigned char  serNo[8],
int *  ttype 
)

Retrieves the transceiver information for a CAN channel. The application typically uses this call to find out whether a particular CAN channel has a LIN interface connected to it. For a Kvaser LIN Leaf it retrieves the transceiver type and device information.

This function call will open the CAN channel, but no CAN messages are transmitted on it. In other words, it's risk-free to use even if no LIN interface is connected, or if the channel is connected to a CAN system.

Note
Attempts to use the channel for LIN communication will be meaningful only if linGetTransceiverData() stores canTRANSCEIVER_TYPE_LIN or canTRANSCEIVER_TYPE_CANFD_LIN in ttype.
A LIN interface need not be powered for this call to succeed.
The information may not always be accurate. Especially after changing transceiver on a running LAPcan card, you should go on bus and off bus again to be sure the transceiver information is updated.
Parameters
[in]channelThe number of a CAN channel for which the transceiver data will be retrieved.
[out]eanNoA pointer to an array of 8 bytes where the EAN number of the LIN interface will be stored.
[out]serNoA pointer to an array of 8 bytes where the serial number of the LIN interface will be stored.
[out]ttypeA pointer to an integer where the transceiver type will be stored.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linGetFirmwareVersion()

◆ linOpenChannel()

LinHandle linOpenChannel ( int  channel,
int  flags 
)

Open a channel to a LIN interface.

Note
For DRV Lin: The cable must be powered and connected to a LAPcan channel.
For Kvaser LIN Leaf: The Leaf must be powered from the LIN side.
Parameters
[in]channelThe number of the channel. Channel numbering is hardware dependent. This is the same channel number as used by canOpenChannel().
[in]flagsEither one of the following values: LIN_MASTER or LIN_SLAVE.
Returns
If the call succeeds, a handle to the opened channel is returned. The handle is an integer greater than or equal to zero.
If the call fails, the return value is a negative integer indicating an error code. See linERR_xxx for a list of possible error codes.
See also
linClose()

◆ linClose()

LinStatus linClose ( LinHandle  h)

Closes an open handle to a LIN channel. The handle becomes invalid and can not be used in subsequent calls to the LIN functions.

Parameters
[in]hA handle to an open LIN channel.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linOpenChannel()

◆ linGetFirmwareVersion()

LinStatus linGetFirmwareVersion ( LinHandle  h,
unsigned char *  bootVerMajor,
unsigned char *  bootVerMinor,
unsigned char *  bootVerBuild,
unsigned char *  appVerMajor,
unsigned char *  appVerMinor,
unsigned char *  appVerBuild 
)

This function retrieves the firmware version from the LIN interface.

Note
For newer interfaces use linGetChannelData() with linCHANNELDATA_CARD_FIRMWARE_REV instead.
The version numbers aren't valid until linBusOn() has been called.
The firmware in the LIN interface is divided into two parts, the boot code and the application. The boot code is used only when reprogramming (reflashing) the LIN interface. The application handles all LIN communication.
Version numbers are, since the precambric era, divided into a major version number, a minor version number and a build number. These are usually written like, for example, 3.2.12. Here the major number is 3, the minor number 2 and the build number 12.
Parameters
[in]hA handle to an open LIN channel.
[out]bootVerMajorA pointer to a byte where the major version number of the boot code is stored.
[out]bootVerMinorA pointer to a byte where the minor version number of the boot code is stored.
[out]bootVerBuildA pointer to a byte where the build number of the boot code is stored.
[out]appVerMajorA pointer to a byte where the major version number of the application code is stored.
[out]appVerMinorA pointer to a byte where the minor version number of the application code is stored.
[out]appVerBuildA pointer to a byte where the build number of the application is stored.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linGetChannelData()

LinStatus linGetChannelData ( int  channel,
int  item,
void *  buffer,
size_t  bufsize 
)

This function can be used to retrieve certain pieces of information about a channel.

Note
You must pass a channel number and not a channel handle.
Parameters
[in]channelThe number of the channel you are interested in. Channel numbers are integers in the interval beginning at 0
[in]itemThis parameter specifies what data to obtain for the specified channel. The value is one of the constants linCHANNELDATA_xxx.
[out]bufferThe address of a buffer which is to receive the data.
[in]bufsizeThe size of the buffer to which the buffer parameter points.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linSetBitrate()

LinStatus linSetBitrate ( LinHandle  h,
unsigned int  bps 
)

This function sets the bit rate for a master, or the initial bit rate for a slave. The LIN interface should not be on-bus when this function is called.

Note
The LIN Interface should not be on bus.
Supported bit rates are 1000 - 20000 bits per second.
Parameters
[in]hA handle to an open LIN channel.
[in]bpsBit rate in bits per second.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linBusOn()

LinStatus linBusOn ( LinHandle  h)

This function activates the LIN interface.

Note
It will be reset, so any setups done earlier will be lost.
Parameters
[in]hA handle to an open LIN channel.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linBusOff()

◆ linBusOff()

LinStatus linBusOff ( LinHandle  h)

This function deactivates the LIN interface. It will not participate further in the LIN bus traffic.

Parameters
[in]hA handle to an open LIN channel.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linBusOn()

◆ linReadTimer()

unsigned long linReadTimer ( LinHandle  h)

Return the current timer value (used for timestamps)

Note
For convenience, this call returns the timer value instead of passing it in a parameter. This means that if the call fails, it will still return a value (which then is the error code, type casted to a long unsigned integer - e.g. 0xFFFFFFF2 for linERR_INVHANDLE. Watch out.
Parameters
[in]hA handle to an open LIN channel.
Returns
If the call succeeds, the present timer value is returned.

◆ linWriteMessage()

LinStatus linWriteMessage ( LinHandle  h,
unsigned int  id,
const void *  msg,
unsigned int  dlc 
)

Write a LIN message. It is advisable to wait until the message is echoed by linReadMessage() before transmitting a new message, or in case of a schedule table being used, transmit the next message when the previous one is known to be complete.

Note
Only available in master mode.
Parameters
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]msgA pointer to a buffer containing the data of the LIN message.
[in]dlcThe length of the LIN message.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linWriteSync()

◆ linRequestMessage()

LinStatus linRequestMessage ( LinHandle  h,
unsigned int  id 
)

This function writes a LIN message header to the LIN bus. A slave in the system is then expected to fill in the header with data.

Note
This call is only available in master mode.
Parameters
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linReadMessage()

LinStatus linReadMessage ( LinHandle  h,
unsigned int *  id,
void *  msg,
unsigned int *  dlc,
unsigned int *  flags,
LinMessageInfo msgInfo 
)

Read a message from the LIN interface. If a message is available for reception, linOK is returned. This is a non-blocking call. If no message is available in the LIN interface, an error code is returned.

Note
This call will also return echoes of what the LIN interface is transmitting with linWriteMessage. In other words, the LIN interface can hear itself.
Parameters
[in]hA handle to an open LIN channel.
[out]idA pointer to an integer where the identifier of the received LIN message will be stored.
[out]msgA pointer to a buffer where the data of the LIN message will be stored.
[out]dlcA pointer to an integer where the length of the received LIN message will be stored.
[out]flagsA combination of zero or more of the LIN_xxx flags.
[out]msgInfoA pointer to a LinMessageInfo struct where data about the received LIN message will be stored.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linReadMessageWait()

◆ linReadMessageWait()

LinStatus linReadMessageWait ( LinHandle  h,
unsigned int *  id,
void *  msg,
unsigned int *  dlc,
unsigned int *  flags,
LinMessageInfo msgInfo,
unsigned long  timeout 
)

Read a message from the LIN interface. If a message is available for reception, linOK is returned. This is a blocking call. It waits until a message is received in the LIN interface, or the specified timeout period elapses.

Note
This call will also return echoes of what the LIN interface is transmitting with linWriteMessage(). In other words, the LIN interface can hear itself.
Parameters
[in]hA handle to an open LIN channel.
[in]timeoutThe maximum number of milliseconds to wait for a message to be received by the LIN interface.
[out]idA pointer to an integer where the identifier of the received LIN message will be stored.
[out]msgA pointer to a buffer where the data of the LIN message will be stored.
[out]dlcA pointer to an integer where the length of the received LIN message will be stored.
[out]flagsA combination of zero or more of the LIN_xxx flags.
[out]msgInfoA pointer to a LinMessageInfo struct where data about the received LIN message will be stored.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linReadMessage()

◆ linUpdateMessage()

LinStatus linUpdateMessage ( LinHandle  h,
unsigned int  id,
const void *  msg,
unsigned int  dlc 
)

This function updates a message buffer in a slave. The contents of the message buffer will be used the next time the slave is polled for the specified LIN message id.

Note
The LIN Interface must be on bus.
Parameters
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]msgA pointer to a buffer containing the data of the LIN message.
[in]dlcThe length of the LIN message.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linClearMessage()

◆ linSetupIllegalMessage()

LinStatus linSetupIllegalMessage ( LinHandle  h,
unsigned int  id,
unsigned int  cFlags,
unsigned int  delay 
)

Using this function, it is possible to use the LIN interface to create corrupted LIN messages. You call the function once for each LIN identifier that should be affected.

To return to normal mode, either restart the LIN interface (by going off bus and on the bus again) or call the function with delay and cFlags set to zero.

Note
The LIN Interface must be on bus for this command to work.
It is supported in firmware version 2.4.1 and later.
Parameters
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]cFlagsOne or more of the LIN_MSG_DISTURB_xxx flags.
[in]delayThe delay parameter will result in a delay of this many bittimes after the header and before the first data byte.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linSetupLIN()

◆ linSetupLIN()

LinStatus linSetupLIN ( LinHandle  h,
unsigned int  lFlags,
unsigned int  bps 
)

This function changes various settings on a LIN Interface that is on bus. When going on bus, the bit rate and the flag values listed below are set to the default value (either as hard-coded in the firmware, or as stored in the non-volatile memory of the LIN Interface).

With this function, you can do one or more of the following things:

  • Select checksum according to LIN 2.0
  • Turn variable message length off. The message length then will depend on the message ID.

In master mode it is also possible to change the bit rate without going off bus first.

Note
The LIN Interface must be on bus for this command to work.
It is supported in firmware version 2.5.1 and later.
For LIN 2.0 compliance, you must specify both LIN_ENHANCED_CHECKSUM and LIN_VARIABLE_DLC.
Parameters
[in]hA handle to an open LIN channel.
[in]lFlagsOne or more of the following flags: LIN_ENHANCED_CHECKSUM, LIN_VARIABLE_DLC
bpsSpecifies the bit rate in bits per second. This parameter can be used only in master mode. The bit rate is set without going off bus.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linSetupIllegalMessage()

◆ linWriteWakeup()

LinStatus linWriteWakeup ( LinHandle  h,
unsigned int  count,
unsigned int  interval 
)

Write a wakeup frame.

If count is zero, one single wakeup frame is transmitted. If count > 1, several wakeup frames are transmitted spaced with 'interval' bittimes. The LIN interface will interrupt the sequence when a LIN message or another command is received. The stream of wakeups will be recived as incoming messages with the LIN_RX flag bit set.

Parameters
[in]hA handle to an open LIN channel.
[in]countThe number of wakeup frames to send.
[in]intervalThe time, in bit times, between the wakeup frames.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linClearMessage()

LinStatus linClearMessage ( LinHandle  h,
unsigned int  id 
)

Clear a message buffer for a LIN slave. The message buffer will not answer next time it is polled.

Parameters
[in]hA handle to an open LIN channel.
[in]idThe LIN message id for which the corresponding buffer will be cleared.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure

◆ linWriteSync()

LinStatus linWriteSync ( LinHandle  h,
unsigned long  timeout 
)

Call this function to make sure all messages transmitted to the LIN Interface has been received by it.

When messages are transmitted to the LIN Interface, they are queued by the driver before appearing on the CAN bus.

The function returns linOK if all writes are done, linERR_TIMEOUT in case of timeout or possibly some other error code.

If the LIN Interface is in master mode and a LIN message has been transmitted with linWriteMessage(), this function will return when the LIN Interface has received the message. If another LIN messa ge is being received or transmitted, the message will not be transmitted on the LIN bus at once. And even if the LIN Interface is idle, the header of the new message will just have been started when linWriteSync() retur ns.

After calling linUpdateMessage() and linClearMessage() for a slave, this function is enough to know that the LIN Interface is updated.

After linWriteMessage(), it is advisable to wait until the message is echoed by linReadMessage() before transmitting a new message, or in case of a schedule table being used, transmit the next message when the previous one is known to be complete.

When, in master mode, a message should be transmitted after a poll (reception) is done, it might be necessary to call linWriteMessage() before the result is received via linReadMessage() as the LIN Interface waits up to the maximum frame length before knowing a received message is complete. A new message to transmit will force completion if the currently received one.

Parameters
[in]hA handle to an open LIN channel.
[in]timeoutThe maximum number of milliseconds to wait for the queued messages to be transmitted by the LIN interface.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure
See also
linWriteMessage()

◆ linGetCanHandle()

LinStatus linGetCanHandle ( LinHandle  h,
unsigned int *  canHandle 
)

Return the CAN handle given an open LIN handle

Parameters
[in]hA handle to an open LIN channel.
[out]canHandleA pointer to an integer where the CAN handle will be stored.
Returns
linOK (zero) if success
linERR_xxx (negative) if failure