🔓 Understand the syntax structure of the LIN protocol at once? How to parse and edit LDF, and decode and encode LIN frames?

In the article on understanding the LIN protocol, we have initially grasped the basic data structure of the LIN bus. How are these structures stored in a computer? And how are they transmitted?

1 LIN Description File LDF

The LIN Description File (LDF) is a text file that describes a complete Local Interconnect Network (LIN) cluster according to the ISO 17987-1 standard. There are now many management tools that can visually load LDF files, such as Vector’s LDF Explorer, which facilitates the management/analysis of related LIN cluster communications.

2 LDF Syntax

2.1 Global Configuration Information

The global information configuration of the LDF file includes the protocol version and communication baud rate.

LIN_description_file;
LIN_protocol_version = "2.2";
LIN_language_version = "2.2";
LIN_speed = 19.2 kbps;

2.2 Nodes

<span>Nodes</span> lists the names of all LIN masters and slaves.

Nodes {
    // Master node: node name, time base (5/10ms), jitter (0~0.5ms)
    Master: LIN_Master, 10 ms, 0.1 ms ;
    // Slave nodes: node name1, node name2...
    Slaves: Slave_1 ;
}

2.3 Slave Node Attributes

Node_attributes  { // Slave node attributes definition, mapped to the second part node definition
    // Slave node name
    Slave_1 {
        LIN_protocol = "2.2"; // Protocol version
        configured_NAD = 0x1 ; // Default Node Address (NAD, 1-255/0x01~0xFF)
        // Sequentially for supplier_id (0~0x7FFE), function_id (0~0xFFFE), variant (0~0xFF)
        product_id = 0x36,0xF10B,255 ;
        // Optional LIN bus error detection signal name (1bit)
        response_error = MANDATORY_RESPONSE_ERROR_SIGNAL;
        P2_min = 50 ms;         // Minimum interval
        ST_min = 50 ms;         // Minimum preparation time
        N_As_timeout = 1000 ms; // Optional diagnostic frame transmission time
        N_Cr_timeout = 1000 ms; // Optional time from the end of the previous frame to the start of the next continuous frame
        configurable_frames {
            // Includes all frames processed by the slave node (unconditional frames, event-triggered frames, sporadic frames)
            Slave2Master_1 ;
            Slave2Master_2 ;
        }
    }
}

2.4 Schedule Tables

<span>Schedule_tables</span> describes a set of schedule tables, defining different tables for different situations, usually including one for “daily operation”. Each table has a unique name and contains a list of LIN frames followed by a frame slot time. Note that if the time base setting of the LDF (set in Nodes) is 10 milliseconds, then the slot time must be an integer multiple of the time base. Some frames in the table are repeated to increase the frequency of selecting signals.

Schedule_tables {
    MainTable {
        // Frame name delay frame slot time
        Slave2Master_1 delay 30 ms ;
        Slave2Master_2 delay 30 ms ;
        Master2Slave_1 delay 30 ms ;
        Master2Slave_2 delay 30 ms ;
    }
}

2.5 Frames

All unconditional LIN frames defined in the LIN cluster are presented here.

Frames {
    // Frame name: Frame ID, LIN node publishing the frame, frame length
    Slave2Master_1:1, Slave_1,8{
        // Signal name, signal starting bit
        Slave2Master_DATA0,0 ;
        Slave2Master_DATA1,8 ;
        Slave2Master_DATA2,16 ;
        Slave2Master_DATA3,24 ;
        Slave2Master_DATA4,32 ;
        Slave2Master_DATA5,40 ;
        Slave2Master_DATA6,48 ;
        Slave2Master_DATA7,56 ;
    }
    Master2Slave_2:17, LIN_Master,1{
        Master2Slave_NewSignal,0 ;
    }
    Master2Slave_1:2, LIN_Master,8{
        Master2Slave_1_DATA0,0 ;
        Master2Slave_1_DATA1,8 ;
        Master2Slave_1_DATA2,16 ;
        Master2Slave_1_DATA3,24 ;
        Master2Slave_1_DATA4,32 ;
        Master2Slave_1_DATA5,40 ;
        Master2Slave_1_DATA6,48 ;
        Master2Slave_1_DATA7,56 ;
    }
    Slave2Master_2:16, Slave_1,1{
        Slave2Master_2_DATA0,0 ;
    }
}

2.6 Diagnostic Frames

The following settings are generally used by default without changes.

Diagnostic_frames {
    // Master node diagnostic sending frame: MasterReq, Frame ID: 0x3c or 60
    MasterReq:60{
        MasterReqB0,0 ;
        MasterReqB1,8 ;
        MasterReqB2,16 ;
        MasterReqB3,24 ;
        MasterReqB4,32 ;
        MasterReqB5,40 ;
        MasterReqB6,48 ;
        MasterReqB7,56 ;
    }
    // Slave node diagnostic receiving frame: SlaveResp, Frame ID: 0x3d or 61
    SlaveResp:0x3d{
        SlaveRespB0,0 ;
        SlaveRespB1,8 ;
        SlaveRespB2,16 ;
        SlaveRespB3,24 ;
        SlaveRespB4,32 ;
        SlaveRespB5,40 ;
        SlaveRespB6,48 ;
        SlaveRespB7,56 ;
    }
}

2.7 Signals

<span>Signal</span> defines all signals in the frame, including signal length, default/initial values, the node publishing the signal, and the list of nodes receiving the signal.

Signals {
    // Signal name: signal size (bit), initial default value (array), sending node, receiving node
    Slave2Master_DATA0:8,0, Slave_1, LIN_Master ;
    ...
    Master2Slave_NewSignal:8,{255}, LIN_Master, Slave_1 ;
    Master2Slave_1_DATA0:8,0, LIN_Master, Slave_1 ;
    ...
    Slave2Master_2_DATA0:8,0, Slave_1, LIN_Master ;
}

2.8 Diagnostic Signals

The following settings are generally used by default without changes.

Diagnostic_signals {
    MasterReqB0:8,0 ;
    MasterReqB1:8,0 ;
    MasterReqB2:8,0 ;
    MasterReqB3:8,0 ;
    MasterReqB4:8,0 ;
    MasterReqB5:8,0 ;
    MasterReqB6:8,0 ;
    MasterReqB7:8,0 ;
    SlaveRespB0:8,0 ;
    SlaveRespB1:8,0 ;
    SlaveRespB2:8,0 ;
    SlaveRespB3:8,0 ;
    SlaveRespB4:8,0 ;
    SlaveRespB5:8,0 ;
    SlaveRespB6:8,0 ;
    SlaveRespB7:8,0 ;
}

3 LDF Software/Library Applications

In practical applications, LDF can be created and edited using a simple text editor, even Notepad. However, a better approach is to use existing LDF development software and library functions:

• • Vector LDF Explorer: Vector’s LDF Explorer can open LDF files and quickly identify consistency errors
• • Intrepid LDF Tool: This tool allows you to open, edit, create, and diagnose LDF files
• • ldfparser^[1]: An open-source Python library for parsing LDF files

Below, we take <span>ldfparser</span> as an example.

3.1 Parsing Files

Before parsing, you need to import the library file; the installation process of the library file is omitted here. If you already have a <span>Python</span> environment, you can run <span>pip install ldfparser</span> directly in the terminal to complete the installation.

import ldfparser
# Parse to dictionary
ldf = ldfparser.parse_ldf_to_dict('lin_bus.ldf')
# Parse to object
ldf = ldfparser.parse_ldf('lin_bus.ldf')

3.2 Frame Encoding and Decoding

Encoding is the process of converting the provided LIN signals into a complete frame.

# Encode using raw values and pack into the frame
frame = ldf.get_unconditional_frame('Master2Slave_2')
encode_frame = frame.encode_raw({'Master2Slave_NewSignal': [0]})
print(encode_frame)
>>> bytearray(b'\x00')

# Encode using signal encoder
frame = ldf.get_frame("Slave2Master_1")
encode_frame = frame.encode({'Slave2Master_DATA3': 255})
print(encode_frame)
>>> bytearray(b'\x00\x00\x00\xff\x00\x00\x00\x00')

# Decoding also has decode and decode_raw methods
frame = ldf.get_frame("Master2Slave_1")
decode_frame = frame.decode(b'\x00 \x01 \x02 \x03 \x04 \x05 \x06 \x07 \x08')
print(decode_frame)
>>> {'Master2Slave_1_DATA0': 0, 'Master2Slave_1_DATA1': 32, 'Master2Slave_1_DATA2': 1, 'Master2Slave_1_DATA3': 32, 'Master2Slave_1_DATA4': 2, 'Master2Slave_1_DATA5': 32, 'Master2Slave_1_DATA6': 3, 'Master2Slave_1_DATA7': 32}

3.3 Getting Signals

signal = ldf.get_signal('Master2Slave_NewSignal')

3.4 Diagnostic Frames

ldf.master_request_frame.encode_assign_nad(inital_nad=0, supplier_id=0x7FFF, function_id=0xFFFF, new_nad=0x13)

ldf.slave_response_frame.decode_response(b'\x00\x01\xF0\xFF\xFF\xFF\xFF\xFF')

3.5 Schedule Tables

schedule_table = ldf.get_schedule_table('MainTable')
for entry in schedule_table.schedule:
    print(f"{type(entry).__name__} - {entry.delay * 1000} ms")

The examples above cover most application scenarios; everyone can practice with existing LDF files.

💡 Tips: LDF can also be converted to DBC with one click!

Reference Links

<span>[1]</span> ldfparser: https://c4deszes.github.io/ldfparser/parser.html

Since you’ve read this far, why not give a like + follow to support the author? 🙏 Your support is the motivation for my continued creation!