socan and MultiCAN
==================

.. note::
   In order to use socan in the `MultiCAN <https://mcan.sourceforge.io/>`_ 
   device support, you have to change a configuration file in 
   `MultiCAN <https://mcan.sourceforge.io/>`_. See
   :ref:`configure MultiCAN <config_MultiCAN>` how to do this.
   You must also build socan with a differnt build target, this is also 
   described in the section mentioned above.

`MultiCAN <https://mcan.sourceforge.io/>`_ is a CAN
multi protocol library and
`EPICS <https://epics-controls.org/>`_ device support.

`MultiCAN <https://mcan.sourceforge.io/>`_ is open source 
and available for the operating systems 
`Linux <https://en.wikipedia.org/wiki/Linux>`_,
`vxWorks <https://en.wikipedia.org/wiki/VxWorks>`_ and
`RTEMS <https://www.rtems.org/>`_.

MultiCAN protocols
------------------

`MultiCAN <https://mcan.sourceforge.io/>`_ 
implements higher level CAN Bus protocols like 
`CANOpen <https://en.wikipedia.org/wiki/CANopen>`_ and parts of
the older
`CAN Application Layer (CAL) <http://overpof.free.fr/schneider/CAN%20&%20CANopen/CANopen/%A9CiA%20CANCANopen%20CD%20V5.1/html/spec2.htm>`_ standard.

EPICS support
-------------

`MultiCAN <https://mcan.sourceforge.io/>`_ is also a CAN Bus device support for the
`Experimental Physics Industrial Control System (EPICS) <https://epics-controls.org/>`_.

`EPICS <https://epics-controls.org/>`_ is a software framework for developing
distributed control systems. It is mostly used in the science community for 
controlling research facilities like synchrotron radiation sources. MultiCAN was 
developed and is used at the 
`Helmholtz-Zentrum Berlin <https://www.helmholtz-berlin.de/index_en.html>`__.

The SCI API
-----------

The `Simple CAN Interface (SCI) <https://mcan.sourceforge.io/sci-index.html>`_
is an API that was developed with 
`MultiCAN <https://mcan.sourceforge.io/>`_. The intention was to have a
hardware abstraction layer to the CAN Bus device so that higher level
parts of
`MultiCAN <https://mcan.sourceforge.io/>`_ could be implemented 
hardware independent.

MultiCAN operating systems and hardware
---------------------------------------

MultiCAN has implementations of
`SCI <https://mcan.sourceforge.io/sci-index.html>`__
for `VME Bus <https://en.wikipedia.org/wiki/VMEbus>`_ 
computer systems with a `VME-CAN4 <https://esd.eu/en/products/vme-can4>`_ card
and the operating systems
`vxWorks <https://en.wikipedia.org/wiki/VxWorks>`_ or
`RTEMS <https://www.rtems.org/>`_.

More recently, an implementation of
`SCI <https://mcan.sourceforge.io/sci-index.html>`__
for CAN to TCP/IP hat rail modules was added. These modules are connected to
the `VME Bus <https://en.wikipedia.org/wiki/VMEbus>`_ system or
Linux PC by ethernet.

This was the first time
`MultiCAN <https://mcan.sourceforge.io/>`_ could be compiled and used with Linux.
However, the connection via ethernet and TCP/IP worsens the real time
properties of the CAN bus interface.

MultiCAN support of Linux and CAN devices on a PC with socan
------------------------------------------------------------

By using the sci library of the socan package,
`MultiCAN <https://mcan.sourceforge.io/>`_ now supports 
CAN interface cards with Linux that are directly connected to the PC, e.g. PCI
cards or USB adapters. The software only needs a 
`SocketCAN <https://www.kernel.org/doc/html/latest/networking/can.html>`_
interface for these devices. With the 
`PCAN-PCI Express FD <https://www.peak-system.com/PCAN-PCI-Express-FD.414.0.html?&L=1>`_
card we not even need an extra driver, since this driver is part of the 
standard Linux kernel.

With the socan package and 
`MultiCAN <https://mcan.sourceforge.io/>`_ we can now
run 
`EPICS <https://epics-controls.org/>`_ 
`IOCs <https://docs.epics-controls.org/en/latest/getting-started/EPICS_Intro.html>`_
on Linux PCs that have directly connected CAN Bus interface.

.. _config_MultiCAN:

Configure MultiCAN
------------------

For reasons of backwards compatbility, 
`MultiCAN <https://mcan.sourceforge.io/>`_ is by default configured to
use the "scan" driver when compiled for linux. This is the 
driver for CAN to TCP/IP hat rail modules mentioned earlier.

In order to compile 
`MultiCAN <https://mcan.sourceforge.io/>`_ with socan, change 
file 'configure/CONFIG" there. Make sure that the following entries are set::

  USE_VCAN_Linux=NO
  USE_SCAN_Linux=NO
  USE_SOCAN_Linux=YES

This configures 
`MultiCAN <https://mcan.sourceforge.io/>`_ to use the socan library instead of
scan.

You must also add an entry to file 'configure/RELEASE' (insert correct path
below)::

  SOCAN=<PATH-TO-SOCAN-MODULE>

Finally you must not build socan with ``make``, use::

  make epics

instead. This creates a library directory with a different name that is needed by 
`EPICS <https://epics-controls.org/>`_.