.. _can_host_tests:

Controller Area Network (CAN) Host Tests
########################################

Overview
********

This test suite uses `python-can`_ for testing Controller Area Network (CAN) communication between a
host PC (running :ref:`Twister <twister_script>`) and a device under test (DUT) running Zephyr.

Prerequisites
*************

The test suite has the following prerequisites:

* The python-can library installed on the host PC.
* A CAN fixture creating a CAN bus between the host PC and the DUT.

The Zephyr end of the CAN fixture can be configured as follows:

* The CAN controller to be used is set using the ``zephyr,canbus`` chosen devicetree node.
* The CAN bitrates are set using :kconfig:option:`CONFIG_CAN_DEFAULT_BITRATE` and
  :kconfig:option:`CONFIG_CAN_DEFAULT_BITRATE_DATA`, but can be overridden on a board level using
  the ``bitrate`` and ``bitrate-data`` CAN controller devicetree properties if needed. Default
  bitrates are 125 kbits/s for the arbitration phase/CAN classic and 1 Mbit/s for the CAN FD data
  phase when using bitrate switching (BRS).

The host end of the CAN fixture can be configured through python-can. Available configuration
options depend on the type of host CAN adapter used. The python-can library provides a lot of
flexibility for configuration as decribed in the `python-can configuration`_ page, all centered
around the concept of a configuration "context. The configuration context for this test suite can be
configured as follows:

* By default, the python-can configuration context is not specified, causing python-can to use the
  default configuration context.
* A specific configuration context can be provided along with the ``can`` fixture separated by a
  ``:`` (i.e. specify fixture ``can:zcan0`` to use the ``zcan0`` python-can configuration context).
* The configuration context can be overridden using the ``--can-context`` test suite argument
  (i.e. run ``twister`` with the ``--pytest-args=--can-context=zcan0`` argument to use the ``zcan0``
  python-can configuration context).

Building and Running
********************

Running on native_sim
=====================

Running the test suite on :ref:`native_sim` relies on the `Linux SocketCAN`_ virtual CAN driver
(vcan) providing a virtual CAN interface named ``zcan0``.

On the host PC, a virtual SocketCAN interface needs to be created and brought up before running the
test suite:

.. code-block:: shell

   sudo ip link add dev zcan0 type vcan
   sudo ip link set up zcan0

Next, python-can needs to be configured for the ``zcan0`` interface. One option is to use a
dedicated ``zcan0`` context in the ``~/.canrc`` configuration file as shown here:

.. code-block:: ini

   [zcan0]
   interface = socketcan
   channel = zcan0
   fd = True

Once the virtual SocketCAN interface has been created, brought up, and configured the test suite can
be launched using Twister:

.. code-block:: shell

   west twister -v -p native_sim/native/64 -X can:zcan0 -T tests/drivers/can/host/

After the test suite has completed, the virtual SocketCAN interface can be removed again:

.. code-block:: shell

   sudo ip link del zcan0

Running on Hardware
===================

Running the test suite on hardware requires a physical CAN adapter connected to the host PC. The CAN
adapter must be supported by python-can. The examples below assumes using a Linux SocketCAN
interface named ``can0``. For other platforms/adapters, please see the `python-can`_ documentation.

The CAN bus of the CAN adapter must be connected to the CAN connector of the device under test.
Make sure the CAN bus is terminated with 120 ohm resistors at both ends. The termination resistor
may already be present on the device under test, but CAN adapters typically require external bus
termination.

.. code-block:: shell

   # Leave out "dbitrate 1000000 fd on" if can0 does not support CAN FD
   sudo ip link set can0 type can restart-ms 1000 bitrate 125000 dbitrate 1000000 fd on
   sudo ip link set up can0

Next, python-can needs to be configured for the ``can0`` interface. One option is to use a dedicated
``can0`` context in the ``~/.canrc`` configuration file as shown here:

.. code-block:: ini

   [can0]
   interface = socketcan
   channel = can0
   # Set "fd = False" if can0 does not support CAN FD
   fd = True

Once the SocketCAN interface has been brought up and configured the test suite can be launched using
Twister. Below is an example for running on the :ref:`lpcxpresso55s36`:

.. code-block:: shell

   west twister -v -p lpcxpresso55s36/lpc55s36 --device-testing --device-serial /dev/ttyACM0 -X can:can0 -T tests/drivers/can/host/

After the test suite has completed, the SocketCAN interface can be brought down again:

.. code-block:: shell

   sudo ip link set down can0

.. _python-can:
   https://python-can.readthedocs.io

.. _python-can configuration:
   https://python-can.readthedocs.io/en/stable/configuration.html

.. _Linux SocketCAN:
   https://www.kernel.org/doc/html/latest/networking/can.html