1.. _can_host_tests:
2
3Controller Area Network (CAN) Host Tests
4########################################
5
6Overview
7********
8
9This test suite uses `python-can`_ for testing Controller Area Network (CAN) communication between a
10host PC (running :ref:`Twister <twister_script>`) and a device under test (DUT) running Zephyr.
11
12Prerequisites
13*************
14
15The test suite has the following prerequisites:
16
17* The python-can library installed on the host PC.
18* A CAN fixture creating a CAN bus between the host PC and the DUT.
19
20The Zephyr end of the CAN fixture can be configured as follows:
21
22* The CAN controller to be used is set using the ``zephyr,canbus`` chosen devicetree node.
23* The CAN bitrates are set using :kconfig:option:`CONFIG_CAN_DEFAULT_BITRATE` and
24  :kconfig:option:`CONFIG_CAN_DEFAULT_BITRATE_DATA`, but can be overridden on a board level using
25  the ``bitrate`` and ``bitrate-data`` CAN controller devicetree properties if needed. Default
26  bitrates are 125 kbits/s for the arbitration phase/CAN classic and 1 Mbit/s for the CAN FD data
27  phase when using bitrate switching (BRS).
28
29The host end of the CAN fixture can be configured through python-can. Available configuration
30options depend on the type of host CAN adapter used. The python-can library provides a lot of
31flexibility for configuration as decribed in the `python-can configuration`_ page, all centered
32around the concept of a configuration "context. The configuration context for this test suite can be
33configured as follows:
34
35* By default, the python-can configuration context is not specified, causing python-can to use the
36  default configuration context.
37* A specific configuration context can be provided along with the ``can`` fixture separated by a
38  ``:`` (i.e. specify fixture ``can:zcan0`` to use the ``zcan0`` python-can configuration context).
39* The configuration context can be overridden using the ``--can-context`` test suite argument
40  (i.e. run ``twister`` with the ``--pytest-args=--can-context=zcan0`` argument to use the ``zcan0``
41  python-can configuration context).
42
43Building and Running
44********************
45
46Running on native_sim
47=====================
48
49Running the test suite on :ref:`native_sim` relies on the `Linux SocketCAN`_ virtual CAN driver
50(vcan) providing a virtual CAN interface named ``zcan0``.
51
52On the host PC, a virtual SocketCAN interface needs to be created and brought up before running the
53test suite:
54
55.. code-block:: shell
56
57   sudo ip link add dev zcan0 type vcan
58   sudo ip link set up zcan0
59
60Next, python-can needs to be configured for the ``zcan0`` interface. One option is to use a
61dedicated ``zcan0`` context in the ``~/.canrc`` configuration file as shown here:
62
63.. code-block:: ini
64
65   [zcan0]
66   interface = socketcan
67   channel = zcan0
68   fd = True
69
70Once the virtual SocketCAN interface has been created, brought up, and configured the test suite can
71be launched using Twister:
72
73.. code-block:: shell
74
75   west twister -v -p native_sim/native/64 -X can:zcan0 -T tests/drivers/can/host/
76
77After the test suite has completed, the virtual SocketCAN interface can be removed again:
78
79.. code-block:: shell
80
81   sudo ip link del zcan0
82
83Running on Hardware
84===================
85
86Running the test suite on hardware requires a physical CAN adapter connected to the host PC. The CAN
87adapter must be supported by python-can. The examples below assumes using a Linux SocketCAN
88interface named ``can0``. For other platforms/adapters, please see the `python-can`_ documentation.
89
90The CAN bus of the CAN adapter must be connected to the CAN connector of the device under test.
91Make sure the CAN bus is terminated with 120 ohm resistors at both ends. The termination resistor
92may already be present on the device under test, but CAN adapters typically require external bus
93termination.
94
95.. code-block:: shell
96
97   # Leave out "dbitrate 1000000 fd on" if can0 does not support CAN FD
98   sudo ip link set can0 type can restart-ms 1000 bitrate 125000 dbitrate 1000000 fd on
99   sudo ip link set up can0
100
101Next, python-can needs to be configured for the ``can0`` interface. One option is to use a dedicated
102``can0`` context in the ``~/.canrc`` configuration file as shown here:
103
104.. code-block:: ini
105
106   [can0]
107   interface = socketcan
108   channel = can0
109   # Set "fd = False" if can0 does not support CAN FD
110   fd = True
111
112Once the SocketCAN interface has been brought up and configured the test suite can be launched using
113Twister. Below is an example for running on the :ref:`lpcxpresso55s36`:
114
115.. code-block:: shell
116
117   west twister -v -p lpcxpresso55s36/lpc55s36 --device-testing --device-serial /dev/ttyACM0 -X can:can0 -T tests/drivers/can/host/
118
119After the test suite has completed, the SocketCAN interface can be brought down again:
120
121.. code-block:: shell
122
123   sudo ip link set down can0
124
125.. _python-can:
126   https://python-can.readthedocs.io
127
128.. _python-can configuration:
129   https://python-can.readthedocs.io/en/stable/configuration.html
130
131.. _Linux SocketCAN:
132   https://www.kernel.org/doc/html/latest/networking/can.html
133