Road vehicles - Local Interconnect Network (LIN) - Part 5: Application programmers interface (API)
1 Scope
This document has been established in order to define the LIN application programmers interface (API).
This document applies to the application program interface definition for LIN communication.
2 Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ISO 17987-2 Road vehicles - Local Interconnect Network (LIN) - Part 2: Transport protocol and network layer services
Note: GB/T 42691.2-2023, Road vehicles - Local Interconnect Network (LIN) - Part 2: Transport protocol and network layer services (ISO 17987-2:2016, IDT)
ISO 17987-3 Road vehicles - Local Interconnect Network (LIN) - Part 3: Protocol specification
Note: GB/T 42691.3-2023, Road vehicles - Local Interconnect Network (LIN) - Part 3: Protocol specification (ISO 17987-3:2016, IDT)
3 Terms, definitions and abbreviated terms
3.1 Terms and definitions
For the purposes of this document, the terms and definitions given in ISO 17987-2 and ISO 17987-3 apply.
3.2 Symbols
The following symbols apply to this document.
||: logical OR binary operation
3.3 Abbreviated terms
The following Abbreviated terms apply to this document.
API: application programmers interface
OSI: open systems interconnection
PDU: protocol data unit
RX: Rx pin of the transceiver
UART: universal asynchronous receiver transmitter
4 API definitions
4.1 LIN cluster generation
The LIN Description file (LDF; see ISO 17987-2) is parsed by a tool and generates a configuration for the LIN device driver. The node capability language specification (NCF) is normally not used in this process since its intention is to describe a hardware slave node, and therefore, does not need the API. See ISO 17987-2 for a description of the workflow and the roles of the LDF and NCF.
4.2 Concept of operations
4.2.1 General
The API is split in three areas
a) LIN core API,
b) LIN node configuration and identification API, and
c) LIN transport layer API (optional).
4.2.2 LIN core API
The LIN core API handles initialization, processing and a signal based interaction between the application and the LIN core. This implies that the application does not have to bother with frames and transmission of frames. Notification exists to detect transfer of a specific frame if this is necessary, see 4.3.5. API calls to control the LIN core also exist.
Two versions exist of most of the API calls
a) static calls embed the name of the signal or interface in the name of the call, and
b) dynamic calls provide the signal or interface as a parameter.
Note: The named objects (signals, schedules) defined in the LDF extends their names with the channel postfix name (see channel postfix name definition in ISO 17987-2).
4.2.3 LIN node configuration and identification API
The LIN node configuration and identification API is service-based (request/response), i.e. the application in the master node calls an API routine that transmits a request to the specified slave node and awaits a response. The slave node device driver automatically handles the service.
The behaviour of the LIN node configuration and identification API is covered in the node configuration and identification (see ISO 17987-3).
4.2.4 LIN transport layer API
The LIN transport layer is message based. Its intended use is to work as a transport layer for messages to a diagnostic message parser outside of the LIN device driver. Two exclusively alternative APIs exist, one raw that allows the application to control the contents of every frame sent and one messaged-based that performs the full transport layer function.
The behaviour of the LIN transport layer API is defined in ISO 17987-2.
4.3 API conventions
4.3.1 General
The LIN core API has a set of functions (see Table 1) all based on the idea to give the API a separate name space, in order to minimize the risk of conflicts with existing software. All functions and types have the prefix “l_” (lowercase “L” followed by an “underscore”).
Road vehicles - Local Interconnect Network (LIN) - Part 5: Application programmers interface (API)
1 Scope
This document has been established in order to define the LIN application programmers interface (API).
This document applies to the application program interface definition for LIN communication.
2 Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ISO 17987-2 Road vehicles - Local Interconnect Network (LIN) - Part 2: Transport protocol and network layer services
Note: GB/T 42691.2-2023, Road vehicles - Local Interconnect Network (LIN) - Part 2: Transport protocol and network layer services (ISO 17987-2:2016, IDT)
ISO 17987-3 Road vehicles - Local Interconnect Network (LIN) - Part 3: Protocol specification
Note: GB/T 42691.3-2023, Road vehicles - Local Interconnect Network (LIN) - Part 3: Protocol specification (ISO 17987-3:2016, IDT)
3 Terms, definitions and abbreviated terms
3.1 Terms and definitions
For the purposes of this document, the terms and definitions given in ISO 17987-2 and ISO 17987-3 apply.
3.2 Symbols
The following symbols apply to this document.
||: logical OR binary operation
3.3 Abbreviated terms
The following Abbreviated terms apply to this document.
API: application programmers interface
OSI: open systems interconnection
PDU: protocol data unit
RX: Rx pin of the transceiver
UART: universal asynchronous receiver transmitter
4 API definitions
4.1 LIN cluster generation
The LIN Description file (LDF; see ISO 17987-2) is parsed by a tool and generates a configuration for the LIN device driver. The node capability language specification (NCF) is normally not used in this process since its intention is to describe a hardware slave node, and therefore, does not need the API. See ISO 17987-2 for a description of the workflow and the roles of the LDF and NCF.
4.2 Concept of operations
4.2.1 General
The API is split in three areas
a) LIN core API,
b) LIN node configuration and identification API, and
c) LIN transport layer API (optional).
4.2.2 LIN core API
The LIN core API handles initialization, processing and a signal based interaction between the application and the LIN core. This implies that the application does not have to bother with frames and transmission of frames. Notification exists to detect transfer of a specific frame if this is necessary, see 4.3.5. API calls to control the LIN core also exist.
Two versions exist of most of the API calls
a) static calls embed the name of the signal or interface in the name of the call, and
b) dynamic calls provide the signal or interface as a parameter.
Note: The named objects (signals, schedules) defined in the LDF extends their names with the channel postfix name (see channel postfix name definition in ISO 17987-2).
4.2.3 LIN node configuration and identification API
The LIN node configuration and identification API is service-based (request/response), i.e. the application in the master node calls an API routine that transmits a request to the specified slave node and awaits a response. The slave node device driver automatically handles the service.
The behaviour of the LIN node configuration and identification API is covered in the node configuration and identification (see ISO 17987-3).
4.2.4 LIN transport layer API
The LIN transport layer is message based. Its intended use is to work as a transport layer for messages to a diagnostic message parser outside of the LIN device driver. Two exclusively alternative APIs exist, one raw that allows the application to control the contents of every frame sent and one messaged-based that performs the full transport layer function.
The behaviour of the LIN transport layer API is defined in ISO 17987-2.
4.3 API conventions
4.3.1 General
The LIN core API has a set of functions (see Table 1) all based on the idea to give the API a separate name space, in order to minimize the risk of conflicts with existing software. All functions and types have the prefix “l_” (lowercase “L” followed by an “underscore”).
