.. socan documentation master file, created by
   sphinx-quickstart on Fri Aug  2 23:48:31 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. image:: logo_hzb_big.png
   :align: right
   :target: http://www.helmholtz-berlin.de

=================================
Welcome to socan's documentation!
=================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


socan is a high level library for using the
`CAN bus <http://en.wikipedia.org/wiki/CAN_bus>`_
with `Linux <https://en.wikipedia.org/wiki/Linux>`_.

It uses the 
`SocketCAN <https://www.kernel.org/doc/html/latest/networking/can.html>`_
interface for accessing CAN bus devices.

socan can be used as 
`SCI API <https://mcan.sourceforge.io/sci-index.html>`__
by `MultiCAN <https://mcan.sourceforge.io/>`_, a CAN
multi protocol library and
`EPICS <https://epics-controls.org/>`_ device support.

The software was tested with the following hardware:

- `PCAN-PCI Express FD <https://www.peak-system.com/PCAN-PCI-Express-FD.414.0.html?&L=1>`_
  by `PEAK-System <https://www.peak-system.com/Home.59.0.html?&L=1>`_
- `PCAN-USB <https://www.peak-system.com/PCAN-USB.199.0.html?L=1>`_
  by `PEAK-System <https://www.peak-system.com/Home.59.0.html?&L=1>`_
- `USB2CAN-Cable <https://www.inno-maker.com/product/usb2can-cable/>`_
  by `innomaker <https://www.inno-maker.com/>`_

It should work with any other Linux CAN Bus device that has a
`SocketCAN <https://www.kernel.org/doc/html/latest/networking/can.html>`_
interface implemented.

It also works with the
`Virtual CAN Bus interface <https://docs.kernel.org/networking/can.html#the-virtual-can-driver-vcan>`_
that is integrated in modern Linux kernels.

The software should run on any modern (from 2024 on) Linux distribution and
was tested with Fedora 39, Fedora 41 and Debian 12.

See :doc:`introduction` for more information.

:Author:
    Goetz Pfeiffer (Goetz.Pfeiffer@helmholtz-berlin.de, goetzpf@googlemail.com)

:Version:
    |version|

.. seealso::
   `Goetz Pfeiffer's Project site <https://gp-projects.sourceforge.io/>`_
   for other open source projects.

Documentation
-------------

Introduction
++++++++++++

This gives more details on the design and features of socan:

:doc:`Introduction to socan <introduction>`

Reference documents
+++++++++++++++++++

- `socan package <doxygen/html/index.html>`_
- `socan API <doxygen/html/socan_8h.html>`_
- `sci API of the socan package <doxygen/html/sci_8h.html>`_

Full list of documents
++++++++++++++++++++++

.. toctree::
   :maxdepth: 1

   introduction
   dependencies
   can_setup
   build
   socan_library
   sci_library
   socan_multican
   programs
   example
   license

License and copyright
---------------------

Copyright (c) 2025 by `Helmholtz-Zentrum Berlin <https://www.helmholtz-berlin.de>`__.

This software of this project can be used under GPL v.3, see :doc:`license`.

socan at sourceforge
--------------------

You find the sourceforge summary page for socan at
`socan at Sourceforge <https://sourceforge.net/projects/socan>`_.

Getting the source, build and install the application
-----------------------------------------------------

How to get, build and install socan is described at :doc:`build`.

Example programs
----------------

Two simple examples are described at :doc:`example`.

Indices and tables
------------------

* :ref:`genindex`
* :ref:`search`