Contents:

LIN Interfaces¶

The AutobusGW (ABGW) supports LIN protocol v2.2A (in the relevant hardware configurations). The LIN interfaces are implemented in FPGA and therefore provide jitter-free operation. Slave mode operatoin is currently supported (Master upon request). It is possible to both passively listen-in on LIN Traffic and to act as a slave for a subset or all LIN frames configured. Every physical LIN port can emulate several frames (i.e. slaves).

Operating the LIN interfaces requires first configuring the interface with RESTAPI. Frame payload update and reception of LIN Frame Data is possible using a TCP socket connection. The listen-only frames can be directly read on the socket connection without further action (upon reception on the LIN bus). Updating the payload cache inside the LIN port is accomplished by writing the corresponding data via the TCP socket. The data communication on the TCP socket level is on the frame ID and raw frame content level. Signal definitions are transparent to the ABGW.

Support for diagnostic frames is available upon request.

Configuring LIN Interfaces¶

The configuration of LIN ports is achieved using the following REST API Endpoints: * A global setting for the LIN TCP listening port under /lin/tcp_config * Per-port LDF Upload endpoint /lin/ldf_upload/<int:ch> * Per-port LIN Config endpoint /lin/config/<int:ch> with struct lin_config_t

TCP Port¶

In order to activate the LIN TCP gateway, it is required to write the port number into the tcp_port field of the /lin/tcp_config struct.

LDF Upload¶

Every LIN Bus endpoint must have apriori information regarding the frames to be encountered. The LDF file contains information about frames and their lengths. Frame length information is required for CRC calculation, since frame length is not transmitted on the bus.

As a first step in configuring a LIN port, it is possible to upload the relevant LDF file first. The LDF will populate the frame_config array under /lin/config/<int:ch> with the relevant lengths. After uploading an LDF, it will be assumed that all non-master frames are to be transmitted by the ABGW LIN port.

Alternatively, it is possible to update the lin_config endpoints with all LIN frames without uploading an LDF file.

IMPORTANT NOTICE

Do note that it is advised to define the lengths of ALL frames on the LIN Bus, including the ones in which one has no interest in either generating or listening to. In case the ABGW encounters a frame_id which is not enabled, a best effort reception will be attempted. The payload length will be automatically detected and enhanced checksum will be assumed in this case. In case of a valid checksum, the received frame is then forwarded to the TCP interface.

LIN Port Configuration¶

Every array element of lin_config_t contains the configuration of a single LIN channel and has the following fields:

enabled (bool)

The port is enabled if this is set to true.

baudrate_bps (uint32)

The desired LIN Baudrate in bauds per second. This field can be set to zero for autodetection using the SYNC field. The functionality of break-in-data requires setting a baudrate to avoid ambiguity between the start bit of a slow bitrate and a break sequence of a faster bitrate.

enable_error_frames (bool)

If set to true, error conditions will be reported on the TCP interface. The error conditions are signalled using msg_type. A msg_type of 0 indicates the reception of an known (i.e. enabled) frame with the expected length and CRC type. Other values indicate either best effort reception, some deviation from the enabled configuration, or an error event. Refer to the table of message types.

enable_tx_echos (bool)

If set to true, a tx_echo frame will be sent on the TCP interface to signal the transmission of a LIN frame.

stucklow_trip_ms (uint32)

The value of he maximum amount of time the LIN bus is allowed to be low (dominant state) before MSG_IDLE_BUS_STUCK_LOW is communicated over the TCP interface. The message will be continuously sent every stucklow_trip_ms milliseconds until the bus recovers and is back high. Set to 0 (default) to deactivate.

frame_config (array of length 64 of frame_config_t)

This array contains one element per frame ID. It is possible to PUT an incomplete list of frames, provided that all entries contain frame_id. Every frame_config element contains the following fields:

enabled (boolean): Setting to true indicates that the frame is activated. If a disabled frame is encountered on the bus, a best effort receive attempt is performed and an enhanced checksum is assumed.
do_simulate (boolean): If enabled, the LIN port will answer requests for this Frame ID, instead of just receiving frame data.
length_bytes (uint32): Length of frame in bytes. Must be correctly set for all frames defined on the bus. This can also be set by uploading an LDF file to the specified port.
enhanced_checksum (bool): If enabled, activates enhanced checksum for this frame (includes PID in checksum calculation). Classic checksum is used when this is set to false.
comment (String: max length 15): Optional user comment.
frame_id (uint8):: frame_id corresponds to the LIN Frame ID. If this property is set in one array element of the array being PUT, it must be set for all others.

LIN TCP Interface Operation¶

A single TCP client may update the payload of or listen to any configured LIN port.

The TCP Frame format is shown below:

struct lin_frame_tcpformat_t¶

struct lin_frame_tcpformat {
    uint8_t msg_type;        //refer to table of message types
    uint8_t frame_length;    //in bytes. For TX, frame_length defined using RESTAPI is the valid one and this field is ignored.
    uint8_t frame_id;        //LIN Frame ID
    uint8_t lin_port_index0; //zero based LIN physical port index
    uint8_t crc_type;        //received or transmitted crc type: [0: classic, 1:enhanced] (only valid for RX or TX_ECHO frames)
    uint8_t crc_byte;        //value of the crc byte (only valid for RX or TX_ECHO frames)
    uint8_t reserved_0;      //
    uint8_t reserved_1;      //
    struct {
        uint32_t tv_sec;
        uint32_t tv_usec;
    } hw_timestamp;
    uint8_t payload[8];      //payload bytes, partially filled for smaller frames
};

Every LIN Port contains an internal cache of Frame payloads to be transmitted when requested on the bus. This cache can be updated by sending the above data structure over the TCP socket to the LIN TCP listening port. In the transmit direction, msg_type should be set to zero.

In the receive direction, all connected TCP clients will receive a copy of all LIN Frames from all LIN ports. The lin_port_index0 field is used to differentiate between physical LIN ports.

To ensure proper operation, please configure the LIN Port via REST API before commencing with TCP traffic. Online configuration of additional LIN ports while others are operating is supported.

Message Types¶

The following table lists the possible message types which can be received over the TCP interface. Note that all messages which differ from MSG_RX_OK (with all its variations) only get communicated if enable_error_frames is enabled.

ID	Short Name	Description
0x00	MSG_RX_OK	An enabled frame has been successfully received with matching length and matching crc type.
0x01	MSG_RX_OK_LENGTH_MISMATCH	An enabled frame has been successfully received with mis-matching length and matching crc type.
0x02	MSG_RX_OK_CRCTYPE_MISMATCH	An enabled frame has been successfully received with matching length and mismatching crc type.
0x03	MSG_RX_OK_LENGTH_AND_CRCTYPE_MISMATCH	An enabled frame has been successfully received with mismatching length and mismatching crc type.
0x04	MSG_RX_OK_BEST_EFFORT	A non-enabled frame has been successfully received. The length and crc type have been automatically detected.
0x05	MSG_RX_NO_RESPONSE	Timeout occurred while waiting for a response for the frame ID.
0x06	MSG_RX_CHECKSUM_ERROR	Received checksum does not match the calculated checksum.
0x10	MSG_IDLE_BUS_STUCK_LOW	The stucklow_trip_ms timer has expired while the bus is in a low state.
0x11	MSG_BREAK_TOO_SHORT	Break is too short.
0x12	MSG_BREAK_OR_WAKE_TOO_LONG	Break (or possible wake) is too long.
0x13	MSG_BREAK_DELIMITER_TOO_SHORT	Break delimiter too short.
0x14	MSG_BREAK_WAKE_DETECTED	A wake event has been detected.
0x15	MSG_BREAK_DELIMITER_TOO_LONG	Break delimiter too short.
0x16	MSG_BREAK_IN_DATA	A break-in-data condition occured, the old frame being interrupted will possibly generate its own error message.
0x21	MSG_SYNC_ILLEGAL_BIT_DURATION	Bitrate is outside of plausible range of 1<->20kbps.
0x22	MSG_SYNC_INVALID_BIT_PATTERN	SYNC bit pattern does not equal 0x55.
0x23	MSG_SYNC_INTERBYTE_SPACING_TOO_LONG	Timeout while waiting for ID field to start.
0x31	MSG_ID_PARITY_ERROR	Parity error detected.
0x32	MSG_ID_INVALID_STOP_BIT	Invalid stop bit value.
0x40	MSG_TX_ECHO	Echo of a frame that got transmitted.
0x41	MSG_TX_BUS_STUCK_HIGH	A bus-contention event was detected while attempting to transmit a low (dominant) bit.

LIN Interfaces