.. index::
   CAN-Bus

==========================================
CAN Bus Specifications and Troubleshooting
==========================================

The `CAN bus <http://en.wikipedia.org/wiki/CAN_bus>`_ is a robust
`field bus <https://en.wikipedia.org/wiki/Fieldbus>`_ that is used in
:doc:`IDCP <idcp>` for communication between the
`IOC <https://docs.epics-controls.org/en/latest/guides/EPICS_Intro.html?highlight=IOC#ioc-software-components>`_ and motor control devices, power supplies and temperature sensors.

Cabling
-------

We use a shielded twisted pair cable with 9 pin
`D-Sub <https://en.wikipedia.org/wiki/D-subminiature>`_
plugs.

This is the pin-allocation as we use it here:

=====   =======   ==================================
Pin     Signal    Description
=====   =======   ==================================
2       CAN_L     CAN bus signal (dominant low)
3       CAN_GND   CAN ground
7       CAN_H     CAN bus signal (dominant high)
=====   =======   ==================================

Topology
--------

All participants on the CAN bus must be connected
in `bus <https://en.wikipedia.org/wiki/Bus_network>`_ topology.
You must not have branches on your network.

Termination
-----------

With our standard cable the CAN bis must be
`terminated <https://en.wikipedia.org/wiki/Electrical_termination>`_
with 120 Ohm at both ends.

VME-CAN4 Interface card
-----------------------

For `VME <http://en.wikipedia.org/wiki/VMEbus>`_ bus
`IOCs <https://docs.epics-controls.org/en/latest/guides/EPICS_Intro.html?highlight=IOC#ioc-software-components>`_
we use mostly the VME-CAN4 interface card for CAN Bus communication.

Manual
++++++

The hardware manual can be found here:

`VME-CAN4 hardware manual <https://esd.eu/fileadmin/esd/docs/manuals/en/VME-CAN4_Manual_en_H15_S12_Vx11_DN17.pdf>`_.

VME-CAN4 diagnostic LEDs
++++++++++++++++++++++++

.. |br| raw:: html

  <br/>

.. _ref_can_diagnose_LED:

There are three rows with 4 LEDs each:

+--------------+--------------+--------------+----------------+
| Column A     | Column B     | Column C     | Column D       |
+==============+==============+==============+================+
| LED1:A |br|  | LED1:B |br|  | LED1:C |br|  | LED1:D |br|    |
| red |br|     | yellow |br|  | red |br|     | green, |br|    |
| SYSFAIL      | BUS          | IRQ          | always off     |
+--------------+--------------+--------------+----------------+
| LED2:A |br|  | LED2:B |br|  | LED2:C |br|  | LED2:D |br|    |
| green |br|   | green |br|   | green |br|   | green |br|     |
| Status CPU 1 | Status CPU 2 | Status CPU 3 | Status CPU 4   |
+--------------+--------------+--------------+----------------+
| LED3:A |br|  | LED3:B |br|  | LED3:C |br|  | LED3:D |br|    |
| red |br|     | red |br|     | red |br|     | red |br|       |
| Error CAN 1  | Error CAN 2  | Error CAN 3  | Error CAN 4    |
+--------------+--------------+--------------+----------------+

LED states:

+------------------+--------------------------+-----------------------------------------+
| LED              | LED off                  | LED on                                  |
+==================+==========================+=========================================+
| LED 1:A |br|     | SYSFAIL not active.      | SYSFAIL active |br|                     |
| red |br|         |                          | The signal is active if at least |br|   |
| SYSFAIL          |                          | one CPU is not initialized. The |br|    |
|                  |                          | SYSFAIL signal is guided to the VMEbus. |
+------------------+--------------------------+-----------------------------------------+
| LED 1:B |br|     | No VMEbus access |br|    | Access from VMEbus to |br|              |
| yellow |br|      | to the VME-CAN4.         | the VME-CAN4.                           |
| BUS              |                          |                                         |
+------------------+--------------------------+-----------------------------------------+
| LED 1:C |br|     | No VMEbus interrupt |br| | The VMEbus-interrupt |br|               |
| red |br|         | of the VME-CAN4 is |br|  | signal of the VME-CAN4 |br|             |
| IRQ              | active.                  | is active.                              |
+------------------+--------------------------+-----------------------------------------+
| LED 1:D |br|     | From PCB version >= BAxxxx on, this LED is no longer |br|          |
| green |br|       | in use. The LED is always off.                                     |
| User             |                                                                    |
+------------------+--------------------------+-----------------------------------------+
| LED2:A...D |br|  | The respective CPU |br|  | The initialization of |br|              |
| green |br|       | is not initialized.      | the CPU has been |br|                   |
| Status CPU1...4  |                          | successfully completed.                 |
+------------------+--------------------------+-----------------------------------------+
| LED 3:A...D |br| | The error flag of |br|   | The error flag of the |br|              |
| red |br|         | the respective CAN |br|  | respective CAN controller |br|          |
| Error CAN 1...4  | controller is inactive.  | is active.                              |
+------------------+--------------------------+-----------------------------------------+

CAN Cable lengths
-----------------


With the CAN bus, the baud rate limits the maximum cable length.

+----------------+----------------------------------+---------------------------------+
|  Bit rate |br| | Typical values of reachable |br| | CiA recommendations |br|        |
|  [Kbit/s]      | wire length with esd |br|        | (07/95) for reachable wire |br| |
|                | interface lmax [m]               | lengths lmin [m]                |
+================+==================================+=================================+
|  1000          |                                37|  25                             |
+----------------+----------------------------------+---------------------------------+
|  800           |                                59|  50                             |
+----------------+----------------------------------+---------------------------------+
|  666.6         |                                80|                                 |
+----------------+----------------------------------+---------------------------------+
|  500           |                               130|  100                            |
+----------------+----------------------------------+---------------------------------+
|  333.3         |                               180|                                 |
+----------------+----------------------------------+---------------------------------+
|  250           |                               270|  250                            |
+----------------+----------------------------------+---------------------------------+
|  166           |                               420|                                 |
+----------------+----------------------------------+---------------------------------+
|  125           |                               570|  500                            |
+----------------+----------------------------------+---------------------------------+
|  100           |                               710|  650                            |
+----------------+----------------------------------+---------------------------------+
|  66.6          |                              1000|                                 |
+----------------+----------------------------------+---------------------------------+
|  50            |                              1400|  1000                           |
+----------------+----------------------------------+---------------------------------+
|  33.3          |                              2000|                                 |
+----------------+----------------------------------+---------------------------------+
|  20            |                              3600|  2500                           |
+----------------+----------------------------------+---------------------------------+
|  12.5          |                              5400|                                 |
+----------------+----------------------------------+---------------------------------+
|  10            |                              7300|  5000                           |
+----------------+----------------------------------+---------------------------------+

..
   Note: from https://stackoverflow.com/questions/7348208/how-to-right-align-columns-content-in-restructuredtext-simple-tables
   Use '| <unicode 0x2001' after the pipe to keep whitespace alignment

Troubleshooting
---------------

If you don't have a connection check the following.

Termination
+++++++++++

The CAN bus *must have* termination of 120 Ohm at both ends. Without
termination it only works for very short cable lengths in the region of 1m.

A common problem is that the termination resistor is missing at one or both
ends.

The VME-CAN4 card sometimes has a termination resistor directly on the card.

In newer installations we use D-Sub connections with a built-in resistor that
can be switched on and off.

If the termination resistors are in the connector you can unplug all CAN
devices and measure the resistance between PIN 2 and 7. With correct
termination at both ends you should measure 60 Ohm.

Connectors
++++++++++

Open connectors and check that PINs 2, 3 and 7 are connected to the correct
wires. Make sure that CAN_H and CAN_L are not swapped.

Ports
+++++

The VME-CAN4 card has 4 CAN Bus ports. Make sure that the cable is plugged to
the right port.

This is the current CAN Port use with IDCP, note that we start counting with
zero here:

.. _ref_can_diagnose_ports:

+----------+---------------------------------+------------+
| CAN Port | Usage                           | Baud rate  |
+==========+=================================+============+
| 0        | Connection to monochromator     | 500 kBit   |
+----------+---------------------------------+------------+
| 1        | Connection to Collectior IOC    |  66 kBit   |
+----------+---------------------------------+------------+
| 2        | Connection to motor controllers | 1 MBit     |
|          | (UniDrive)                      |            |
+----------+---------------------------------+------------+
| 3        | Connection to power supplies    | 1 MBit     |
|          | and temperature modules         |            |
+----------+---------------------------------+------------+

Connecting the cable to the wrong port disrupts communication between all other
participants if the Baud rate doesn't match.

Diagnose with a Linux Notebook
++++++++++++++++++++++++++++++

.. _ref_can_diagnose_notebook:

Any Linux notebook with a CAN-USB interface that is supported by the Linux
kernel can be used to diagnose problems further.

First you have to initialize the CAN interface with the correct baud rate
*before* you connect it to your CAN bus line. The baud must be an integer
between 10000 and 1000000, the transfer speed in Bit/sec.

Enter::

  sudo ip link set can0 type can bitrate BAUDRATE
  sudo ip link set can0 txqueuelen 1000
  sudo ip link set up can0

You can see your can interface with::

  ip link show type can

You must have the program 'candump' installed. Usually this is part of a
package named "can-utils".

You start a simple diagnose with::

  candump -t A can0

candump has many options, see also ``candump -h``.

CAN line to the monochromator
+++++++++++++++++++++++++++++

Diagnose with LED
:::::::::::::::::

As described at 
:ref:`VME-CAN4 LEDs<ref_can_diagnose_LED>` in the third row of LEDs there is an LED for each CAN port.

If the *first LED in the third row* is red, there is a CAN communication
problem with the monochromator detected by the CAN bus card. The CAN bus card
can detect if there isn't *any* receiver on the CAN bus line. If the VME CAN
interface card on the monochromator is set up with the correct baud rate and
connected to the undulator and the CAN cable termination is correct, you
shouldn't see a red LED.

Diagnose with channel access
::::::::::::::::::::::::::::

For an undulator with name DEVICENAME enter::

  watch -n 1 caget -a DEVICENAME:BaseStatIStat

If you see ``TIMEOUT`` or ``TIMEOUT invalid`` the undulator didn't get a response
from the monochromator.

Diagnose with Linux notebook
::::::::::::::::::::::::::::

When you use a Linux notebook as described at
:ref:`Linux notebook<ref_can_diagnose_notebook>`.

Ensure that the baud rate of the CAN bus interface of the linux notebook is
correct. Baud rates are shown here :ref:`Baud rates<ref_can_diagnose_ports>`.
Usually the baud rate here is 500 kBit.

.. caution::
   A wrong baud rate on the Linux notebook will disrupt all CAN communication.

You should see, among others, the CAN objects shown below. The undulator IOC
sends the outgoing CAN objects at least every 5 seconds:

+---------------+---------------------+--------------------------+-------------+--------------+
| Variable      | outgoing CAN object | incoming CAN object |br| | length |br| |  remarks     |
|               |                     | from monochromator       | (bytes)     |              |
+===============+=====================+==========================+=============+==============+
| Gap status    |  724                |   660                    |  5          |  stop: 1     |
| [#f1]_        |                     |                          |             |  run: 3      |
+---------------+---------------------+--------------------------+-------------+--------------+
| Watchdog      |  980                |   916                    |  5          |  increasing  |
| [#f1]_ [#f2]_ |                     |                          |             |  counter     |
+---------------+---------------------+--------------------------+-------------+--------------+

.. [#f1] For each outgoing CAN object you should see a reply by the
         monochromator IOC on the incoming CAN object.

.. [#f2] The watchdog object will be implemented on the monochromator IOC in
         the future. Currently (as of 2025-06-17) you will not see a reply
         here. 

Now you can do the following to locate the problem:

**Check if the Undulator IOC has a problem**
............................................

Connect the Undulator IOC directly to the Linux notebook, remove the CAN cable
to the monochromator. Ensure that the CAN termination is still correct. If you
see that the Undulator IOC sends CAN objects, this shows than the CAN bus card
in the Undulator IOC works and the Undulator software works. If not, the
problem is with the Undulator IOC hardware or software.

**Check if the cable prevents the sending of CAN objects**
..........................................................

Keep the Linux notebook connected but attach the CAN bus cable to the
monochromator, too. Ensure that the termination is still correct. This shows if
the problem comes from the cable or something at the monochromator IOCs. Look
if the Undulator gets replies from the monochromator. 

**Check if one of the monochromator IOCs causes the problem**
.............................................................

Unplug *all* monochromators from the cable. If you see that the Undulator IOC
now sends CAN objects, it shows that the cable and it's termination are okay.

Connect each of the monochromators separately, this shows which monochromator
causes the problem.