Doxygen docs

This Arduino library implements a Local Interconnect Network slave node emulation. For an explanation of the LIN bus and protocol e.g. see https://en.wikipedia.org/wiki/Local_Interconnect_Network.

Optionally LIN protocoll via RS485 is supported (see respective examples). In this case Rx-enable (=RE) must be statically enabled to receive LIN echo, and Tx-enable (=DE) is controlled by the Arduino.

The class structure is very flexible and aims at supporting different Serial interfaces and architectures. It can easily be ported to other boards - in which case a pull request is highly appreciated...

For a similar Arduino libary for LIN master emulation see https://github.com/gicking/LIN_master_portable_Arduino

• background handling of frames via user-defined callback functions
• multiple, simultaneous LIN nodes
• supports HardwareSerial and SoftwareSerial
• supports LIN protocoll via RS485 with Tx direction switching

• Arduino AVR boards, e.g. Uno, Mega or Nano
• Arduino AVR Cortex-M boards, e.g. Due
• Arduino Renesas Cortex-M boards, e.g. Uno R4 Minima
• ATtiny boards, e.g. Adafruit Trinket (only SoftwareSerial)
• ESP32 boards, e.g. Arduino Nano-ESP32 or Espressif Wroom-32U
• ESP8266 boards, e.g. Wemos D1 mini
• STM32 boards, e.g. Nucleo-STM32L432KC

• The handler() method must be called at least every 500us. Optionally it can be called from within serialEvent()

• For ESP32 and ESP8266, library EspSoftwareSerial must be installed, even if SoftwareSerial is not used in project

• LIN frame synchronization is via the BREAK signal, which corresponds to a long dominant pulse. On the receiver side this corresponds to 0x00 with missing stop bit (aka framing error, FE). Unfortunately, the Arduino behavior on a FE event is not specified, and different implementations treat it differently. Therefore, this library has to handle frame synchronization differently, depending on Serial type. Specifically:

  • ESP32 HardwareSerial and AVR NeoHWSerial:

    • BREAK is received, FE flag is available
    • sync on Rx==0x00 (= BREAK) with FE==true
    • assert that BREAK is followed by SYNC==0x55
    • this is according to LIN standard and most robust

  • AVR, SAMD, ESP8266 and STM32 HardwareSerial. AVR and Renesas SoftwareSerial:

    • BREAK is received, FE flag not available
    • sync on Rx==0x00 (= BREAK) after minimal inter-frame pause
    • assert that BREAK is followed by SYNC==0x55
    • this is not according to LIN standard and less robust

  • Renesas HardwareSerial. ESP32 & ESP8266 SoftwareSerial:

    • BREAK dropped due to missing stop bit, FE flag not available
    • sync on Rx==0x55 (= SYNC) after minimal inter-frame pause
    • this is not according to LIN standard and least robust

  • STM32 SoftwareSerial:

    • BREAK is received, but sometimes Rx!=0x00, FE flag not available flag not available
    • ignore BREAK due to unreliable value
    • sync on Rx==0x55 (= SYNC) after minimal inter-frame pause
    • this is not according to LIN standard and least robust

• As stated above, default BREAK detection on 8-bit AVR boards is via NeoHWSerial library, which can detect FE. Notes

  • Serial and NeoHWSerial instances are incompatible and must not be used within the same sketch. If possible use only NeoHWSerial for most robust frame synchronization

  • If that is not possible, comment out USE_NEOSERIAL in file LIN_slave_NeoHWSerial_AVR.h to use standard HardwareSerial with less robust synchronization

• SoftwareSerial sending is blocking on all platforms, i.e. "background operation" only applies to receiving master commands

An ok in the below test matrix indicates that normal master request frames are received, slave responses are sent and bus disconnection is detected (-> error). Also, code execution starts with only external supple, i.e. USB not connected. No extensive testing of all possible error cases was performed. Please let me know if you experience unexpected errors.

Logic analyzer screenshots of LIN bus, idle pin and error pin levels are stored in folder "./extras/testing/Board"

Have fun!, Georg

v1.3 (2025-02-06)

• add support for ESP32-S3, Nano Every, STM32, and Uno R4 Minima (no HWSerial, see issue)
• consolidate examples for different boards and LIN/RS485 interfaces
• remove Ticker examples, due to standard 1ms min. period too long

v1.2 (2025-10-28)

• add dependency on EspSoftwareSerial in library.properties
• add notes for EspSoftwareSerial dependency
• in ESP32 Ticker example use standard Ticker.attach() instead of Espressif specific Ticker.attach_us(). Note: ESP8266 has 1ms minimum
• add to integration tests: ESP32 Nano (Arduino ESP32 core) and Wemos Lolin32 Lite (Espressif ESP32 core)
• fixed ESP32 issue if Serial0 undefined, see #3

v1.1 (2025-05-03)

• harmonize with LIN master portable
• simplified debug output via macro
• renamed SERIAL_DEBUG to SERIAL_CONSOLE to avoid mixup with (internal) debug output
• add ESP32 Ticker example to support blocking user functions in loop()
• full regresstion tests and add some comments
• update reference

v1.0 (2025-02-01)

• initial release