The LIN middleware implements LIN 2.2 Slave node for the PSoC 4 devices. Options for the ISO 17987 is also available. The LIN Configurator tool makes it easy to configure the middleware.

Features:

Full LIN 2.2 Slave Node implementation
Compliance with ISO 17987 specification
Full transport layer support
Automatic baud rate synchronization
Automatic detection of bus inactivity
Automatic configuration services
Fully implements a Diagnostic Class I Slave Node
Supports implementation of Diagnostic Class II and III Slave Node
Full error detection
LIN Configurator

General Description

Include mtb_lin.h to get access to all the functions and other declarations in this middleware. See the Quick Start Guide to start using the middleware.

Refer to the release notes for compatibility information.

Refer to the Specification Conformance section for the API deviation from the specification.

The Configuration Considerations section provides the guidance for all operation modes and use cases.

Quick Start Guide

LIN middleware can be used in various Development Environments. Refer to the release notes.

This quick start guide is for an environment with the configured:

CAT2 Peripheral Driver Library (mtb-pdl-cat2)
ModusToolbox Hardware Abstraction Layer (mtb-hal-cat2)
Core Library (core-lib)

The below steps describe the simplest way of enabling the LIN Slave.

STEP 1: Enable the LIN middleware.

Launch ModusToolbox Library Manager and enable the LIN middleware. This step is required only if the ModusToolbox IDE is used. Otherwise, ensure the LIN Middleware is included in your project.

STEP 2: Generate initialization code.

The following code snippet shows the mtbcfg_lin.h header file with the configuration generated by the LIN configurator:

#ifndef MTBCFG_LIN_H
#define MTBCFG_LIN_H
#include "mtb_lin_types.h"
extern mtb_stc_lin_config_t const mtb_lin_0_config;
/* Signal handles used for signal interaction functions. The handle value for a
 * signal matches the value of the handle member of the mtb_stc_lin_signal_t
 * array. The signals with the same name share the same signal handle.
 */
#define MTB_LIN_0_SIGNAL_HANDLE_Response_Error             (0x0000U)
#define MTB_LIN_0_SIGNAL_HANDLE_SignalIn                   (0x0001U)
#define MTB_LIN_0_SIGNAL_HANDLE_SignalOut                  (0x0002U)
/* The low 16 bits minus one corresponds to the signal index in the signals'
 *  configuration array. The every signal has its own flag handle. The signals
 *  with the same name have different flag handles.
 *
 *  The high 16 bits minus one corresponds to the frame index in the frames's
 *  configuration array.
 */
#define MTB_LIN_0_FLAG_HANDLE_Response_Error               (0x00000001U)
#define MTB_LIN_0_FLAG_HANDLE_SignalIn                     (0x00000002U)
#define MTB_LIN_0_FLAG_HANDLE_SignalOut                    (0x00000003U)
#define MTB_LIN_0_FLAG_HANDLE_FrameIn                      (0x00010000U)
#define MTB_LIN_0_FLAG_HANDLE_FrameOut                     (0x00020000U)
#define MTB_LIN_0_FLAG_HANDLE_MRF                          (0x00030000U)
#define MTB_LIN_0_FLAG_HANDLE_SRF                          (0x00040000U)
#endif /* MTBCFG_LIN_H */

The following code snippet shows the mtbcfg_lin.c source file with the configuration generated by the LIN configurator:

/* Frames declaration with initial signals values */
static volatile l_u8  mtb_lin_0_buffer_FrameIn[7U] =
    { 0x00U, 0xFFU, 0xFFU, 0xFFU, 0xFFU, 0xFFU, 0xFFU };
static volatile l_u8  mtb_lin_0_buffer_FrameOut[6U] = { 0xFEU, 0x00U, 0xFFU, 0xFFU, 0xFFU, 0xFFU };
/* The frames' context structure used for the frames' runtime attributes.
 * The size of the array equals to the number of all frames defined plus
 * additional space for the MRF and SRF frames.
 */
mtb_stc_lin_frame_context_t mtb_lin_0_frames_context[4U];
mtb_stc_lin_signal_context_t mtb_lin_0_signals_context[3U];
/* The Master Request Frame (MRF) buffer */
volatile l_u8 mtb_lin_0_raw_rx_buffer[32U];
/* The Slave Response Frame (SRF) buffer */
volatile l_u8 mtb_lin_0_raw_tx_buffer[32U];
volatile mtb_stc_lin_frame_t const mtb_lin_0_frames[] =
{
    {
        // Index: 0,
        // "FrameIn"
        .initial_pid = 0xC1U,
        .direction  = MTB_LIN_FRAME_DIR_SUBSCRIBE,
        .size       = 7U,
        .type       = MTB_LIN_FRAME_TYPE_UNCONDITIONAL,
        .data       = mtb_lin_0_buffer_FrameIn,
    },
    {
        // Index: 1,
        // "FrameOut"
        .initial_pid = 0x80U,
        .direction  = MTB_LIN_FRAME_DIR_PUBLISH,
        .size       = 6U,
        .type       = MTB_LIN_FRAME_TYPE_UNCONDITIONAL,
        .data       = mtb_lin_0_buffer_FrameOut,
    },
};
/* Signal handles used for signal interaction functions.
 * The handle value for a signal matches index in mtb_lin_0_signals[]. */
mtb_stc_lin_signal_t const mtb_lin_0_signals[] =
{
    {
        // Index: 0
        // "Response_Error"
        .handle = 0U,
        .frame_index = 1U,
        .bit_offset  = 0U,
        .type       = MTB_LIN_SIGNAL_TYPE_SCALAR_BOOL,
        .size       = 1U,
    },
    {
        // Index: 1
        // "SignalIn"
        .handle = 1U,
        .frame_index = 0U,
        .bit_offset  = 0U,
        .type       = MTB_LIN_SIGNAL_TYPE_SCALAR_U8,
        .size       = 8U,
    },
    {
        // Index: 2
        // "SignalOut"
        .handle = 2U,
        .frame_index = 1U,
        .bit_offset  = 8U,
        .type       = MTB_LIN_SIGNAL_TYPE_SCALAR_U8,
        .size       = 8U,
    },
};
mtb_stc_lin_config_t const mtb_lin_0_config =
{
    .spec                          = MTB_LIN_SPEC_2_2,
    .iso17987                      = false,
    .inactivity_enabled            = true,
    .inactivity_threshold          = 7000U,
    .break_threshold               = 11U,
    .auto_baud_rate_sync           = true,
    .baud_rate                     = 9600U,
    /* Transport Layer */
    .tl_enabled                    = true,
    .initial_nad                   = 0x10U,
    .tl_api_format                 = MTB_LIN_TL_FORMAT_RAW,
    .tl_buf_len_max                = 512U,
    .tl_tx_queue_len               = 32U,
    .tl_rx_queue_len               = 32U,
    .tl_raw_rx_queue               = mtb_lin_0_raw_rx_buffer,
    .tl_raw_tx_queue               = mtb_lin_0_raw_tx_buffer,
    /* Automatic Configuration Request Handling */
    .auto_config_request_handling  = true,
    .supplier_id                   = 0x7ffeU,
    .function_id                   = 0x4841U,
    .variant                       = 0x00U,
    .service_assign_nad            = true,
    .service_assign_frame_id       = false,
    .service_read_by_id            = true,
    .service_cond_change_nad       = true,
    .service_data_dump             = false,
    .service_target_reset          = false,
    .service_save_config           = true,
    .service_assign_frame_id_range = true,
    /* General frames and signals information */
    .num_of_frames                 = 2U,
    .num_of_signals                = 3U,
    .num_of_signal_handles         = 3U,
    .resp_error_signal_handle      = MTB_LIN_0_SIGNAL_HANDLE_Response_Error,
    .frames                        = mtb_lin_0_frames,
    .signals                       = mtb_lin_0_signals,
    .frames_context                = mtb_lin_0_frames_context,
    .signals_context               = mtb_lin_0_signals_context,
    .file_rev_defined              = false,
};

STEP 3: Update main.c

The following code snippet shows the LIN initialization:

/* Instance number */
#define LIN_IFC_HANDLE          (0U)
/* Interrupt priority for SCB ISR */
#define LIN_SCB_INT_PRIORITY    (0U)
/* Allocate context for LIN operation */
mtb_stc_lin_context_t lin_context;
/* Implement SCB ISR for LIN */
static void LIN_Isr(void)
{
    l_ifc_rx(LIN_IFC_HANDLE, &lin_context);
}
/* Implement Inactivity ISR for LIN */
static void LIN_InactivityIsr(void)
{
    l_ifc_aux(LIN_IFC_HANDLE, &lin_context);
}
/*******************************************************************************
* Function Name: LIN_start
****************************************************************************/
void LIN_start()
{
    /* Initializes the LIN core that is specified by the context structure */
    if (l_sys_init(&mtb_lin_0_config, &lin_context, &LIN_Isr, LIN_SCB_INT_PRIORITY,
                   &LIN_InactivityIsr))
    {
        /* Stop program execution if sys init failed */
        CY_ASSERT(0U);
    }
    /* Initializes the LIN instance that is specified by the context structure.
     * Choose appropriate pins for tx and rx direction from HAL library. */
    if (l_ifc_init(LIN_IFC_HANDLE, &lin_context, P0_4, P0_5))
    {
        /* Stop program execution if ifc init failed */
        CY_ASSERT(0U);
    }
}

STEP 4: Hardware Configuration

Use LIN hardware like CY8CKIT-026-CAN and Lin Shield Kit and CY8CKIT-041S-MAX PSoC 4100S Max Pioneer kit.

STEP 5: Build and program the device.

Connect the device to the LIN Master. Configure LIN Master to send frames and observe updated signals in the LIN Slave application.

Configuration Considerations

This section consists of different guides and instruction of how to enable, configure, and use the LIN middleware in a design. As you can see from the Quick Start Guide section, the settings of the LIN middleware are controlled with the mtb_stc_lin_config_t structure. Please see its description to learn about the parameters and values.

The following is a description of the most common use cases along with the configuration structure examples and code snippets. The list of sections under Configuration Considerations:

LIN Configurator

The standalone LIN Configurator tool helps configure the middleware. The tool output are generated source and header files. Generated files are mandatory for the middleware operation and must be added to your project. The header file provides access to instances of the LIN configuration structure mtb_stc_lin_config_t.

The LIN Configurator tool provides the User Guide, which can be found in the documentation.

Operating Modes

The settings of the LIN middleware are controlled by the mtb_stc_lin_config_t structure. See its description to learn about the parameters and values.

Interrupts

The interrupt is mandatory for LIN middleware operation. The LIN middleware requires two interrupt sources for the proper operation: one for UART operation, other for SysTick timer operation.

The Bus Inactivity Timer is based on the SysTick timer. It is configured by default at Reset time to interrupt a period of 1 millisecond. The LIN middleware uses one callback handler (out of five) from the SysTick timer for one instance. The SysTick timer is configured and enabled automatically during initialization.

The UART interrupt has the configurable priority. Ensure that the UART priority has a level sufficient for a timely response to events on the bus.

Resources

This section describes the software and hardware resources used by the middleware.

For the PSoC 4 devices, the middleware is based on the SCB block.
If Bus Inactivity is enabled, the middleware registers a callback from PDL SysTick driver.
The project described in the Quick Start Guide section, compiled with the GCC compiler's -Og option for CY8C4149AZI-S598 consumes around 33 KB of flash memory and around 800 bytes of RAM memory. The consumption reported for RAM memory is for the .data and .bss sections, without the heap, stack and RAM vectors sections.

Specification Conformance

This section describes the deviations from the API defined by the LIN specifications.

The following deviations are applicable to all functions:
- There are no static functions available. The middleware provides only the dynamic prototypes.
- The interface of each function accepts the pointer to mtb_stc_lin_context_t as a parameter. The context holds the state of the LIN interfaces.
- The interface handle parameter of the Interface Management functions is ignored. The context is used to differentiate between the interfaces instead.
The following functions have the following interface changes:
- The list of parameters and return value of the l_sys_init() function.
- The list of the l_ifc_init() function parameters extended with the RX and TX pin configuration.
- The return type of the l_ifc_ioctl() function changed from l_u16 to mtb_lin_status_t for the enhanced status reporting.
- The data length parameter added to the ld_read_by_id_callout() function.
The deviations from the ISO 17987 specification are as follows:
- The optional big-endian signal encoding variant is not supported.
- The optional SID B8 is not supported.

API Changes between PSoC Creator Component and Middleware

This section describes the differences between PSoC Creator LIN component and the LIN middleware API.

#	PSoC Creator LIN component	LIN middleware
1	The result of the MTB_LIN_IOCTL_READ_STATUS operation of the l_ifc_ioctl() is returned by the function.	The result of the MTB_LIN_IOCTL_READ_STATUS operation of the l_ifc_ioctl() is returned via the pointer specified by the pv parameter. The function returns MTB_LIN_STATUS_SUCCESS.
2	No l_sys_irq_disable() and l_sys_irq_restore() implemented.	Added implementation of the l_sys_irq_disable() and l_sys_irq_restore().
3	All the interrupt service routines are initialized inside of the component - no any actions required on the application level.	The communication and inactivity interrupt service routines should be implemented on the application level. Refer to the STEP 3: Update main.c section for the more details.

MISRA-C Compliance

This section describes MISRA-C:2012 compliance and deviations for the LIN.

MISRA stands for Motor Industry Software Reliability Association. The MISRA specification covers a set of 10 mandatory rules, 110 required rules, and 39 advisory rules that apply to the firmware design and has been put together by the Automotive Industry to enhance the quality and robustness of the firmware code embedded in automotive devices.

The MISRA specification defines two categories of deviations (see section 5.4 of the MISRA-C:2012 specification):

Project Deviations - applicable for a particular class of deviations.
Specific Deviations - applicable for a single instance in a single file.

Project Deviations and Specific Deviations are documented later in this section.

Specific deviations are also documented in the source code, close to the deviation occurrence. For each deviation, a special macro identifies the relevant rule or directive number, and reason.

Verification Environment

This section provides a MISRA compliance analysis environment description.

Component	Name	Version
Test Specification	MISRA-C:2012 Guidelines for the use of the C language in critical systems	March 2013
MISRA Checking Tool	Coverity Static Analysis Tool	2020.03

Project and Specific Deviations

The list of deviated rules is provided in the table below.

MISRA Rule	Required/Advisory	Rule Description	Description of Deviation(s)
1.2	A	Language extensions are not used	The middleware library supports ISO:C99 standard.
2.5	A	A project does not contain unused macro definitions	The middleware library provides an API to the hardware. The macro is part of the API, which is defined for the application-level only.
3.1	R	The special comment symbols is not used within a comment	Special comment symbols are required for Doxygen comment support, it does not have any impact.
8.7	A	Functions and objects are not defined with external linkage if they are referenced in only one translation unit	The middleware library provides an API to the hardware. The functions and objects with external linkage are part of the API, which are defined for application-level only.
11.4	A	A conversion are not performed between the pointer to an object and an integer type	The cast from an unsigned integer to the pointer does not have any unintended effect, as it is a consequence of the definition of a structure based on hardware registers.
11.5	A	A conversion is not performed from the pointer to void into the pointer to an object	See specific deviations documented in the source code, close to the deviation occurrence.
18.4	A	The +, -, += and -= operators are not applied to an expression of the pointer type	See specific deviations documented in the source code, close to the deviation occurrence.
Directive 4.8	A	If a pointer to the structure or union is never dereferenced within a translation unit, then the implementation of the object is hidden	Deviated, since the object provided by HAL is used without dereferencing for the own needs of LIN middleware.
Directive 4.9	A	A function is used in preference to a function-like macro where they are interchangeable	Deviated, since function-like macros are used to allow more efficient code.

Changelog

Version	Changes	Reason for Change
1.10	Added CAT2 Hardware Abstraction Layers (mtb-hal-cat2) 2.x support./td>
1.0	Initial Version

More Information

For more information, refer to the following documents:

Note: The links to the other software component's documentation (middleware and PDL) point to GitHub to the latest available version of the software. To get documentation of the specified version, download from GitHub and unzip the component archive. The documentation is available in the docs folder.