Introduction
============

The 
`SocketCAN <https://www.kernel.org/doc/html/latest/networking/can.html>`_
API that is part of the Linux kernel allows to directly read and write CAN data
frames to a socket. However, this is a low level interface. For actual CAN Bus
applications you usually have to implement more functionality. socan aims at
providing this additional functionality ready to use.

The socan package consists of two parts:

- :doc:`socan_library`: The CAN Bus library that is based on 
  `SocketCAN <https://www.kernel.org/doc/html/latest/networking/can.html>`_
- :doc:`sci_library`: This implements most parts of the
  `Simple CAN Interface (SCI) <https://mcan.sourceforge.io/sci-index.html>`_.
  This is an older API for the CAN Bus developed at the
  `Helmholtz-Zentrum Berlin <https://www.helmholtz-berlin.de/index_en.html>`__.
  and used by `MultiCAN <https://mcan.sourceforge.io/>`_.

socan has some dependencies on other software packages, these are
described here:

:doc:`dependencies`

socan assumes that the CAN interfaces on your system are already set up. If
they are not you find some hints how to do this at:

:doc:`can_setup`

socan provides some utility scripts and test programs, described here:

:doc:`programs`.

When to use the socan library and when to use the sci library
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

For ordinary CAN bus applications, the socan library would be the right choice.
It's API is simpler than that of the sci library and plugins or duplicated CAN
objects are probably not needed.

The sci library is needed when you want to use
`MultiCAN <https://mcan.sourceforge.io/>`_ or
`EPICS <https://epics-controls.org/>`_ on a Linux PC that has 
CAN devices directly attached. For details on this see
:doc:`socan_multican`.