Road vehicles -- Local Interconnect Network (LIN)

ISO/TR 17987-5:2016 has been established in order to define the LIN application programmers interface (API).

Véhicules routiers -- Réseau Internet local (LIN)

General Information

Status
Published
Publication Date
03-Nov-2016
Current Stage
6060 - International Standard published
Start Date
28-Sep-2016
Completion Date
04-Nov-2016
Ref Project

Buy Standard

Technical report
ISO/TR 17987-5:2016 - Road vehicles -- Local Interconnect Network (LIN)
English language
34 pages
sale 15% off
Preview
sale 15% off
Preview

Standards Content (sample)

TECHNICAL ISO/TR
REPORT 17987-5
First edition
2016-11-15
Road vehicles — Local Interconnect
Network (LIN) —
Part 5:
Application programmers interface
(API)
Véhicules routiers — Réseau Internet local (LIN) —
Partie 5: Interface du programmeur d’application (API)
Reference number
ISO/TR 17987-5:2016(E)
ISO 2016
---------------------- Page: 1 ----------------------
ISO/TR 17987-5:2016(E)
COPYRIGHT PROTECTED DOCUMENT
© ISO 2016, Published in Switzerland

All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form

or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior

written permission. Permission can be requested from either ISO at the address below or ISO’s member body in the country of

the requester.
ISO copyright office
Ch. de Blandonnet 8 • CP 401
CH-1214 Vernier, Geneva, Switzerland
Tel. +41 22 749 01 11
Fax +41 22 749 09 47
copyright@iso.org
www.iso.org
ii © ISO 2016 – All rights reserved
---------------------- Page: 2 ----------------------
ISO/TR 17987-5:2016(E)
Contents Page

Foreword ........................................................................................................................................................................................................................................iv

Introduction ..................................................................................................................................................................................................................................v

1 Scope ................................................................................................................................................................................................................................. 1

2 Normative references ...................................................................................................................................................................................... 1

3 Terms, definitions and abbreviated terms ................................................................................................................................ 1

3.1 Terms and definitions ....................................................................................................................................................................... 1

3.2 Symbols ......................................................................................................................................................................................................... 1

3.3 Abbreviated terms ............................................................................................................................................................................... 1

4 API definitions ........................................................................................................................................................................................................ 1

4.1 LIN cluster generation ...................................................................................................................................................................... 1

4.2 Concept of operations ....................................................................................................................................................................... 2

4.2.1 General...................................................................................................................................................................................... 2

4.2.2 LIN core API ......................................................................................................................................................................... 2

4.2.3 LIN node configuration and identification API ...................................................................................... 2

4.2.4 LIN transport layer API .............................................................................................................................................. 2

4.3 API conventions...................................................................................................................................................................................... 3

4.3.1 General...................................................................................................................................................................................... 3

4.3.2 Data types .............................................................................................................................................................................. 5

4.3.3 Driver and cluster management ......................................................................................................................... 5

4.3.4 Signal interaction............................................................................................................................................................. 5

4.3.5 Notification ........................................................................................................................................................................... 7

4.3.6 Schedule management ................................................................................................................................................ 9

4.3.7 Interface management .............................................................................................................................................10

4.3.8 User provided call outs ............................................................................................................................................16

4.4 Node configuration and identification.............................................................................................................................17

4.4.1 Overview ..............................................................................................................................................................................17

4.4.2 Node configuration .....................................................................................................................................................17

4.4.3 Identification ....................................................................................................................................................................22

4.5 Transport layer ....................................................................................................................................................................................23

4.5.1 Overview ..............................................................................................................................................................................23

4.5.2 Raw- and messaged-based API .........................................................................................................................23

4.5.3 Initialization ......................................................................................................................................................................24

4.5.4 Raw API .................................................................................................................................................................................24

4.5.5 Overview ..............................................................................................................................................................................24

4.5.6 Messaged-based API ..................................................................................................................................................26

4.6 Examples ...................................................................................................................................................................................................30

4.6.1 Overview ..............................................................................................................................................................................30

4.6.2 Master node example ................................................................................................................................................30

4.6.3 Slave node example ....................................................................................................................................................32

Bibliography .............................................................................................................................................................................................................................34

© ISO 2016 – All rights reserved iii
---------------------- Page: 3 ----------------------
ISO/TR 17987-5:2016(E)
Foreword

ISO (the International Organization for Standardization) is a worldwide federation of national standards

bodies (ISO member bodies). The work of preparing International Standards is normally carried out

through ISO technical committees. Each member body interested in a subject for which a technical

committee has been established has the right to be represented on that committee. International

organizations, governmental and non-governmental, in liaison with ISO, also take part in the work.

ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of

electrotechnical standardization.

The procedures used to develop this document and those intended for its further maintenance are

described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the

different types of ISO documents should be noted. This document was drafted in accordance with the

editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives).

Attention is drawn to the possibility that some of the elements of this document may be the subject of

patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of

any patent rights identified during the development of the document will be in the Introduction and/or

on the ISO list of patent declarations received (see www.iso.org/patents).

Any trade name used in this document is information given for the convenience of users and does not

constitute an endorsement.

For an explanation on the meaning of ISO specific terms and expressions related to conformity assessment,

as well as information about ISO’s adherence to the World Trade Organization (WTO) principles in the

Technical Barriers to Trade (TBT) see the following URL: www.iso.org/iso/foreword.html.

The committee responsible for this document is ISO/TC 22, Road vehicles, Subcommittee SC 31, Data

communication.
A list of all parts in the ISO 17987 series can be found on the ISO website.
iv © ISO 2016 – All rights reserved
---------------------- Page: 4 ----------------------
ISO/TR 17987-5:2016(E)
Introduction

ISO 17987 (all parts) specifies the use cases, the communication protocol and physical layer

requirements of an in-vehicle communication network called Local Interconnect Network (LIN).

The LIN protocol as proposed is an automotive focused low speed Universal Asynchronous Receiver

Transmitter (UART) based network. Some of the key characteristics of the LIN protocol are signal-

based communication, schedule table-based frame transfer, master/slave communication with error

detection, node configuration and diagnostic service communication.

The LIN protocol is for low cost automotive control applications, for example, door module and air

condition systems. It serves as a communication infrastructure for low-speed control applications in

vehicles by providing:

— signal-based communication to exchange information between applications in different nodes;

— bit rate support from 1 kbit/s to 20 kbit/s;
— deterministic schedule table-based frame communication;

— network management that wakes up and puts the LIN cluster into sleep mode in a controlled manner;

— status management that provides error handling and error signalling;

— transport layer that allows large amount of data to be transmitted (such as diagnostic services);

— specification of how to handle diagnostic services;
— electrical physical layer specifications;
— node description language describing properties of slave nodes;
— network description file describing behaviour of communication;
— application programmer’s interface;

ISO 17987 (all parts) is based on the open systems interconnection (OSI) Basic Reference Model as

specified in ISO/IEC 7498-1 which structures communication systems into seven layers.

The OSI model structures data communication into seven layers called (top down) application layer

(layer 7), presentation layer, session layer, transport layer, network layer, data link layer and physical layer

(layer 1). A subset of these layers is used in ISO 17987 (all parts).

ISO 17987 (all parts) distinguishes between the services provided by a layer to the layer above it and

the protocol used by the layer to send a message between the peer entities of that layer. The reason for

this distinction is to make the services, especially the application layer services and the transport layer

services, reusable also for other types of networks than LIN. In this way, the protocol is hidden from the

service user and it is possible to change the protocol if special system requirements demand it.

ISO 17987 (all parts) provides all documents and references required to support the implementation of

the requirements related to.

— ISO 17987-1: This part provides an overview of the ISO 17987 (all parts) and structure along with

the use case definitions and a common set of resources (definitions, references) for use by all

subsequent parts.

— ISO 17987-2: This part specifies the requirements related to the transport protocol and the network

layer requirements to transport the PDU of a message between LIN nodes.

— ISO 17987-3: This part specifies the requirements for implementations of the LIN protocol on the

logical level of abstraction. Hardware-related properties are hidden in the defined constraints.

© ISO 2016 – All rights reserved v
---------------------- Page: 5 ----------------------
ISO/TR 17987-5:2016(E)

— ISO 17987-4: This part specifies the requirements for implementations of active hardware

components which are necessary to interconnect the protocol implementation.

— ISO/TR 17987-5: This part specifies the LIN application programmers interface (API) and the

node configuration and identification services. The node configuration and identification services

are specified in the API and define how a slave node is configured and how a slave node uses the

identification service.

— ISO 17987-6: This part specifies tests to check the conformance of the LIN protocol implementation

according to ISO 17987-2 and ISO 17987-3. This comprises tests for the data link layer, the network

layer and the transport layer.

— ISO 17987-7: This part specifies tests to check the conformance of the LIN electrical physical layer

implementation (logical level of abstraction) according to ISO 17987-4.

The LIN API is a network software layer that hides the details of a LIN network configuration (e.g. how

signals are mapped into certain frames) for a user making an application program for an arbitrary

ECU. The user is provided an API, which is focused on the signals transported on the LIN network. A

tool takes care of the step from network configuration to program code. This provides the user with

configuration flexibility. The LIN API is only one possible API existing today beside others like defined

for LIN master nodes in the AUTOSAR standard. Therefore, the LIN API is published as a Technical

Report and all definitions given here are informative only.
vi © ISO 2016 – All rights reserved
---------------------- Page: 6 ----------------------
TECHNICAL REPORT ISO/TR 17987-5:2016(E)
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).

2 Normative references
There are no normative references in this document.
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.

ISO and IEC maintain terminological databases for use in standardization at the following addresses:

— IEC Electropedia: available at http://www.electropedia.org/
— ISO Online browsing platform: available at http://www.iso.org/obp
3.2 Symbols
|| logical OR binary operation
3.3 Abbreviated terms
API application programmers interface
ms millisecond
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

© ISO 2016 – All rights reserved 1
---------------------- Page: 7 ----------------------
ISO/TR 17987-5:2016(E)

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
— LIN core API,
— LIN node configuration and identification API, and
— 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

— static calls embed the name of the signal or interface in the name of the call, and

— 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.
2 © ISO 2016 – All rights reserved
---------------------- Page: 8 ----------------------
ISO/TR 17987-5:2016(E)
4.3 API conventions
4.3.1 General

The LIN core API has a set of functions 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”).
Table 1 — API functions overview
Function Description
DRIVER AND CLUSTER MANAGEMENT
l_sys_init Performs the initialization of the LIN core.
SIGNAL INTERACTION
scalar signal read Reads and returns the current value of the signal.
scalar signal write Reads and returns the current value of the signal.

byte array read Reads and returns the current values of the selected bytes in the signal.

byte array write Sets the current value of the selected bytes in the signal specified by the name sss

to the value specified.
NOTIFICATION

l_flg_tst Returns a C boolean indicating the current state of the flag specified by the name of

the static API call, i.e. returns zero if the flag is cleared, non-zero otherwise.

l_flg_clr Sets the current value of the flag specified by the name of the static API call to zero.

SCHEDULE MANAGEMENT
l_sch_tick Function provides a time base for scheduling.
l_sch_set Sets up the next schedule.
INTERFACE MANAGEMENT

l_ifc_init Initializes the controller specified by the name, i.e. sets up internal functions such

as the baud rate.

l_ifc_goto_sleep This call requests slave nodes on the cluster connected to the interface to enter bus

sleep mode by issuing one go to sleep command.
l_ifc_wake_up The function transmits one wake up signal.

l_ifc_ioctl This function controls functionality that is not covered by the other API calls.

l_ifc_rx The application program is responsible for binding the interrupt and for setting the

correct interface handle (if interrupt is used).

l_ifc_tx The application program is responsible for binding the interrupt and for setting the

correct interface handle (if interrupt is used).

l_ifc_aux This function is used in a slave nodes to synchronize to the break field/sync byte

field sequence transmitted by the master node.

l_ifc_read_status This function returns the status of the previous communication.

© ISO 2016 – All rights reserved 3
---------------------- Page: 9 ----------------------
ISO/TR 17987-5:2016(E)
Table 1 (continued)
Function Description
USER PROVIDED CALL-OUTS

l_sys_irq_disable The user implementation of this function achieves a state in which no interrupts

from the LIN communication occurs.

l_sys_irq_restore The user implementation of this function recovers the previous configured inter-

rupt level.
NODE CONFIGURATION

ld_is_ready This call returns the status of the last requested configuration service.

ld_check_response This call returns the result of the last node configuration service.

ld_assign_frame_id_range This call assigns the protected identifier of up to four frames in the slave node with

the configured NAD.

ld_assign_NAD This call assigns the configured NAD (node diagnostic address) of all slave nodes

that matches the initial_NAD, the supplier ID and the function ID.

ld_save_configuration This call makes a save configuration request to a specific slave node with the given

configured NAD or to all slave nodes if broadcast NAD is set.

ld_read_configuration This call serializes the current configuration (configured NAD and PIDs) and copy

it to the area (data pointer) provided by the application.

ld_set_configuration The function configures the configured NAD and the PIDs according to the config-

uration provided.
IDENTIFICATION

ld_read_by_id The call requests the slave node selected with the configured NAD to return the

property associated with the id parameter.

ld_read_by_id_callout This callout is used when the master node transmits a read by identifier request

with an identifier in the user defined area.
INITIALIZATION

ld_init This call reinitializes the raw or messaged-based layer on the interface.

RAW API

ld_put_raw The call queues the transmission of 8 bytes of data in one frame. The data is sent in

the next suitable MasterReq frame.

ld_get_raw The call copies the oldest received diagnostic frame data to the memory specified

by data.

ld_raw_tx_status The call returns the status of the raw frame transmission function.

ld_raw_rx_status The call returns the status of the raw frame receive function.
MESSAGE-BASED API

ld_send_message The call packs the information specified by data and DataLength into one or multiple

diagnostic frames.

ld_receive_message The call prepares the LIN diagnostic module to receive one message and store it in

the buffer pointed to by data.

ld_tx_status The call returns the status of the last made call to ld_send_message.

ld_rx_status The call returns the status of the last made call to ld_receive_message.

4 © ISO 2016 – All rights reserved
---------------------- Page: 10 ----------------------
ISO/TR 17987-5:2016(E)
4.3.2 Data types
The LIN core defines the following types:
— l_bool 0 is false, and non-zero (>0) is true;
— l_ioctl_op implementation dependent;
— l_irqmask implementation dependent;
— l_u8 unsigned 8 bit integer;
— l_u16 unsigned 16 bit integer;
— l_signal_handle has character string type “signal name”.

In order to gain efficiency, the majority of the functions are static functions (no parameters are needed,

since one function exist per signal, per interface, etc.).
4.3.3 Driver and cluster management
4.3.3.1 l_sys_init
Table 2 defines the l_sys_init.
Table 2 — l_sys_init
Prototype l_bool l_sys_init (void)
Applicability Master and slave nodes.

Description l_sys_init performs the initialization of the LIN core. The scope of the initialization is the

physical node i.e. the complete node (see node composition definition in ISO 17987-2).

The call to the l_sys_init is the first call a user uses in the LIN core before using any other

API functions.
Return value Zero if the initialization succeeded.
Non-zero if the initialization failed.
4.3.4 Signal interaction
4.3.4.1 General

In all signal API calls below the sss is the name of the signal, e.g. l_u8_rd_enginespeed ().

4.3.4.2 Signal types
The signals are of three different types:
— l_bool for one bit signals; zero if false, non-zero otherwise;
— l_u8 for signals of the size 2 bits to 8 bits;
— l_u16 for signals of the size 9 bits to 16 bits.
© ISO 2016 – All rights reserved 5
---------------------- Page: 11 ----------------------
ISO/TR 17987-5:2016(E)
4.3.4.3 Scalar signal read
Table 3 defines the scalar signal read.
Table 3 — Scalar signal read
Dynamic prototype l_bool l_bool_rd (l_signal_handle sss);
l_u8 l_u8_rd (l_signal_handle sss);
l_u16 l_u16_rd (l_signal_handle sss);
Static prototype l_bool l_bool_rd_sss (void);
l_u8 l_u8_rd_sss (void);
l_u16 l_u16_rd_sss (void);
Applicability Master and slave nodes.
Description Reads and returns the current value of the signal.
Reference See ISO 17987-3:2016, 5.1.2.
4.3.4.4 Scalar signal write
Table 4 defines the scalar signal write.
Table 4 — Scalar signal write
Dynamic prototype void l_bool_wr (l_signal_handle sss, l_bool v);
void l_u8_wr (l_signal_handle sss, l_u8 v);
void l_u16_wr (l_signal_handle sss, l_u16 v);
Static prototype void l_bool_wr_sss (l_bool v);
void l_u8_wr_sss (l_u8 v);
void l_u16_wr_sss (l_u16 v);
Applicability Master and slave nodes.
Description Sets the current value of the signal to v.
Reference See ISO 17987-3:2016, 5.1.2.
6 © ISO 2016 – All rights reserved
---------------------- Page: 12 ----------------------
ISO/TR 17987-5:2016(E)
4.3.4.5 Byte array read
Table 5 defines the byte array read.
Table 5 — Byte array read
Dynamic prototype void l_bytes_rd (l_signal_handle sss,
l_u8 start, /* first byte to read from */
l_u8 count, /* number of bytes to read */
l_u8* const data); /* where data is written */
Static prototype void l_bytes_rd_sss (l_u8 start,
l_u8 count,
l_u8* const data);
Applicability Master and slave nodes.

Description Reads and returns the current values of the selected bytes in the signal. The sum of start

and count are never greater than the length of the byte array.

Example Assume that a byte array is 6 bytes long, numbered 0 to 5. Reading byte 2 and 3 from this

array indicates the parameter value start to be 2 (skipping byte 0 and 1) and count to be

2 (reading byte 2 and 3). In this case byte 2 is written to data [0] and byte 3 is written

to data [1].
Reference See ISO 17987-3:2016, 5.1.2.
4.3.4.6 Byte array write
Table 6 defines the byte array write.
Table 6 — Byte array write
Dynamic prototype void l_bytes_wr (l_signal_handle sss,
l_u8 start, /* first byte to write to */
l_u8 count, /* number of bytes to write */
const l_u8* const data); /* where data is read from */
Static prototype void l_bytes_wr_sss (l_u8 start,
l_u8 count,
const l_u8* const data);
Applicability Master and slave nodes.

Description Sets the current value of the selected bytes in the signal specified by the name sss to the

value specified.

The sum of start and count are never greater than the length of the byte array, although

the device driver does not choose to enforce this in runtime.

Example Assume that a byte array is 7 bytes long, numbered 0 to 6. Writing byte 3 and 4 from this

array indicates the parameter value start to be 3 (skipping byte 0, 1 and 2) and count to

be 2 (writing byte 3 and 4). In this case byte 3 is read from data [0] and byte 4 is read

from data [1].
Reference See ISO 17987-3:2016, 5.1.2.
4.3.5 Notification

Flags are local objects in a node and they are used to synchronize the application program with the LIN

core. The flags are automatically set by the LIN core and can only be tested or cleared by the application

© ISO 2016 – All rights reserved 7
---------------------- Page: 13 ----------------------
ISO/TR 17987-5:2016(E)

program. Flags are attached to all types of frames. A flag is set when the frame/signal is considered to

be transmitted respectively received, see reception and transmission in ISO 17987-3.

Three types of flags can be created:
— a flag that is attached to a signal,
— a flag that is attached to a frame, and
— a flag that
...

Questions, Comments and Discussion

Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.