Functions
LIN
LINlib

LIN related functions. More...

## Functions
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 | linSetBitrate (LinHandle h, unsigned int bps)
LinStatus | linBusOn (LinHandle h)
LinStatus | linBusOff (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

LIN related functions.

## Function Documentation

## ◆ linBusOff()

LinStatus linBusOff | ( | LinHandle | h | ) |

Takes the specified handle off-bus.

Note
  Settings and slave message buffers will be reset to the default

Parameters

  [in] | h | A handle to an open LIN channel.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

See also
  linBusOn()

## ◆ linBusOn()

LinStatus linBusOn | ( | LinHandle | h | ) |

Takes the specified handle on-bus.

Note
  Settings and slave message buffers will be reset to the default if
  used on a channel that is already on-bus.

Parameters

  [in] | h | A handle to an open LIN channel.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

See also
  linBusOff()

## ◆ 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] | h | A handle to an open LIN channel.
  [in] | id | The LIN message id for which the corresponding buffer will be cleared.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

## ◆ 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] | h | A handle to an open LIN channel.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

See also
  linOpenChannel()

## ◆ linGetCanHandle()

LinStatus linGetCanHandle | ( | LinHandle | h,
|  | unsigned int * | canHandle
| ) |  |

Return the CAN handle given an open LIN handle

Parameters

  [in] | h | A handle to an open LIN channel.
  [out] | canHandle | A pointer to an integer where the CAN handle will be stored.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

## ◆ 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] | channel | The number of a CAN channel for which the transceiver data will be retrieved.
  [out] | eanNo | A pointer to an array of 8 bytes where the EAN number of the LIN interface will be stored.
  [out] | serNo | A pointer to an array of 8 bytes where the serial number of the LIN interface will be stored.
  [out] | ttype | A 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
  The device must be powered from the LIN side.

Parameters

  [in] | channel | The number of the channel. Channel numbering is hardware dependent. This is the same channel number as used by canOpenChannel().
  [in] | flags | Either 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()

## ◆ 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] | h | A handle to an open LIN channel.
  [out] | id | A pointer to an integer where the identifier of the received LIN message will be stored.
  [out] | msg | A pointer to a buffer where the data of the LIN message will be stored.
  [out] | dlc | A pointer to an integer where the length of the received LIN message will be stored.
  [out] | flags | A combination of zero or more of the LIN_xxx flags.
  [out] | msgInfo | A 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] | h | A handle to an open LIN channel.
  [in] | timeout | The maximum number of milliseconds to wait for a message to be received by the LIN interface.
  [out] | id | A pointer to an integer where the identifier of the received LIN message will be stored.
  [out] | msg | A pointer to a buffer where the data of the LIN message will be stored.
  [out] | dlc | A pointer to an integer where the length of the received LIN message will be stored.
  [out] | flags | A combination of zero or more of the LIN_xxx flags.
  [out] | msgInfo | A 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()

## ◆ 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] | h | A handle to an open LIN channel.
  [in] | id | The identifier of the LIN message.

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.

Note
  The handle shall be off-bus.
  Supported bit rates are 1000 - 20000 bits per second.

Parameters

  [in] | h | A handle to an open LIN channel.
  [in] | bps | Bit rate in bits per second.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

## ◆ 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 handle shall be on-bus.
  It is supported in firmware version 2.4.1 and later.

Parameters

  [in] | h | A handle to an open LIN channel.
  [in] | id | The identifier of the LIN message.
  [in] | cFlags | One or more of the LIN_MSG_DISTURB_xxx flags.
  [in] | delay | The 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 handle 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 handle shall be on-bus.
  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] | h | A handle to an open LIN channel.
  [in] | lFlags | One or more of the following flags: LIN_ENHANCED_CHECKSUM, LIN_VARIABLE_DLC
  | bps | Specifies 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()

## ◆ 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 handle shall be on-bus.

Parameters

  [in] | h | A handle to an open LIN channel.
  [in] | id | The identifier of the LIN message.
  [in] | msg | A pointer to a buffer containing the data of the LIN message.
  [in] | dlc | The length of the LIN message.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

See also
  linClearMessage()

## ◆ 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] | h | A handle to an open LIN channel.
  [in] | id | The identifier of the LIN message.
  [in] | msg | A pointer to a buffer containing the data of the LIN message.
  [in] | dlc | The length of the LIN message.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure

See also
  linWriteSync()

## ◆ 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 LIN 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 message 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() returns.

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] | h | A handle to an open LIN channel.
  [in] | timeout | The 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()

## ◆ 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] | h | A handle to an open LIN channel.
  [in] | count | The number of wakeup frames to send.
  [in] | interval | The time, in bit times, between the wakeup frames.

Returns
  linOK (zero) if success
  linERR_xxx (negative) if failure