1.. _can_shell:
2
3CAN Shell
4#########
5
6.. contents::
7    :local:
8    :depth: 1
9
10Overview
11********
12
13The CAN shell provides a ``can`` command with a set of subcommands for the :ref:`shell <shell_api>`
14module. It allows for testing and exploring the :ref:`can_api` driver API through an interactive
15interface without having to write a dedicated application. The CAN shell can also be enabled in
16existing applications to aid in interactive debugging of CAN issues.
17
18The CAN shell provides access to most CAN controller features, including inspection, configuration,
19sending and receiving of CAN frames, and bus recovery.
20
21In order to enable the CAN shell, the following :ref:`Kconfig <kconfig>` options must be enabled:
22
23* :kconfig:option:`CONFIG_SHELL`
24* :kconfig:option:`CONFIG_CAN`
25* :kconfig:option:`CONFIG_CAN_SHELL`
26
27The following :ref:`Kconfig <kconfig>` options enable additional subcommands and features of the
28``can`` command:
29
30* :kconfig:option:`CONFIG_CAN_FD_MODE` enables CAN FD specific subcommands (e.g. for setting the
31  timing for the CAN FD data phase).
32* :kconfig:option:`CONFIG_CAN_RX_TIMESTAMP` enables printing of timestamps for received CAN frames.
33* :kconfig:option:`CONFIG_CAN_STATS` enables printing of various statistics for the CAN controller
34  in the ``can show`` subcommand. This depends on :kconfig:option:`CONFIG_STATS` being enabled as
35  well.
36* :kconfig:option:`CONFIG_CAN_MANUAL_RECOVERY_MODE` enables the ``can recover`` subcommand.
37
38For example, building the :zephyr:code-sample:`hello_world` sample for the :zephyr:board:`frdm_k64f` with the CAN shell and
39CAN statistics enabled:
40
41.. zephyr-app-commands::
42   :zephyr-app: samples/hello_world
43   :board: frdm_k64f
44   :gen-args: -DCONFIG_SHELL=y -DCONFIG_CAN=y -DCONFIG_CAN_SHELL=y -DCONFIG_STATS=y -DCONFIG_CAN_STATS=y
45   :goals: build
46
47See the :ref:`shell <shell_api>` documentation for general instructions on how to connect and
48interact with the shell. The CAN shell comes with built-in help (unless
49:kconfig:option:`CONFIG_SHELL_HELP` is disabled). The built-in help messages can be printed by
50passing ``-h`` or ``--help`` to the ``can`` command or any of its subcommands. All subcommands also
51support tab-completion of their arguments.
52
53.. tip::
54   All of the CAN shell subcommands take the name of a CAN controller as their first argument, which
55   also supports tab-completion. A list of all devices available can be obtained using the ``device
56   list`` shell command when :kconfig:option:`CONFIG_DEVICE_SHELL` is enabled. The examples below
57   all use the device name ``can@0``.
58
59Inspection
60**********
61
62The properties of a given CAN controller can be inspected using the ``can show`` subcommand as shown
63below. The properties include the core CAN clock rate, the maximum supported bitrate, the number of
64RX filters supported, capabilities, current mode, current state, error counters, timing limits, and
65more:
66
67.. code-block:: console
68
69   uart:~$ can show can@0
70   core clock:      144000000 Hz
71   max bitrate:     5000000 bps
72   max std filters: 15
73   max ext filters: 15
74   capabilities:    normal loopback listen-only fd
75   mode:            normal
76   state:           stopped
77   rx errors:       0
78   tx errors:       0
79   timing:          sjw 1..128, prop_seg 0..0, phase_seg1 2..256, phase_seg2 2..128, prescaler 1..512
80   timing data:     sjw 1..16, prop_seg 0..0, phase_seg1 1..32, phase_seg2 1..16, prescaler 1..32
81   transceiver:     passive/none
82   statistics:
83     bit errors:    0
84       bit0 errors: 0
85       bit1 errors: 0
86     stuff errors:  0
87     crc errors:    0
88     form errors:   0
89     ack errors:    0
90     rx overruns:   0
91
92.. note::
93   The statistics are only printed if :kconfig:option:`CONFIG_CAN_STATS` is enabled.
94
95Configuration
96*************
97
98The CAN shell allows for configuring the CAN controller mode and timing, along with starting and
99stopping the processing of CAN frames.
100
101.. note::
102   The CAN controller mode and timing can only be changed while the CAN controller is stopped, which
103   is the initial setting upon boot-up. The initial CAN controller mode is set to ``normal`` and the
104   initial timing is set according to the ``bitrate``, ``sample-point``, ``bitrate-data``, and
105   ``sample-point-data`` :ref:`devicetree` properties.
106
107Timing
108======
109
110The classic CAN bitrate/CAN FD arbitration phase bitrate can be configured using the ``can bitrate``
111subcommand as shown below. The bitrate is specified in bits per second.
112
113.. code-block:: console
114
115   uart:~$ can bitrate can@0 125000
116   setting bitrate to 125000 bps
117
118If :kconfig:option:`CONFIG_CAN_FD_MODE` is enabled, the data phase bitrate can be configured using
119the ``can dbitrate`` subcommand as shown below. The bitrate is specified in bits per second.
120
121.. code-block:: console
122
123   uart:~$ can dbitrate can@0 1000000
124   setting data bitrate to 1000000 bps
125
126Both of these subcommands allow specifying an optional sample point in per mille and a
127(Re)Synchronization Jump Width (SJW) in Time Quanta as positional arguments. Refer to the
128interactive help of the subcommands for more details.
129
130It is also possible to configure the raw bit timing using the ``can timing`` and ``can dtiming``
131subcommands. Refer to the interactive help output for these subcommands for details on the required
132arguments.
133
134Mode
135====
136
137The CAN shell allows for setting the mode of the CAN controller using the ``can mode``
138subcommand. An example for enabling loopback mode is shown below.
139
140.. code-block:: console
141
142   uart:~$ can mode can@0 loopback
143   setting mode 0x00000001
144
145The subcommand accepts multiple modes given on the same command line (e.g. ``can mode can@0 fd
146loopback`` for setting CAN FD and loopback mode). Vendor-specific modes can be specified in
147hexadecimal.
148
149Starting and Stopping
150=====================
151
152After the timing and mode has been configured as needed, the CAN controller can be started using the
153``can start`` subcommand as shown below. This will enable reception and transmission of CAN frames.
154
155.. code-block:: console
156
157   uart:~$ can start can@0
158   starting can@0
159
160Prior to reconfiguring the timing or mode, the CAN controller needs to be stopped using the ``can
161stop`` subcommand as shown below:
162
163.. code-block:: console
164
165   uart:~$ can stop can@0
166   stopping can@0
167
168Receiving
169*********
170
171In order to receive CAN frames, one or more CAN RX filters need to be configured. CAN RX filters are
172added using the ``can filter add`` subcommand as shown below. The subcommand accepts a CAN ID in
173hexadecimal format along with an optional CAN ID mask, also in hexadecimal format, for setting which
174bits in the CAN ID are to be matched. Refer to the interactive help output for this subcommand for
175further details on the supported arguments.
176
177.. code-block:: console
178
179   uart:~$ can filter add can@0 010
180   adding filter with standard (11-bit) CAN ID 0x010, CAN ID mask 0x7ff, data frames 1, RTR frames 0, CAN FD frames 0
181   filter ID: 0
182
183The filter ID (0 in the example above) returned is to be used when removing the CAN RX filter.
184
185Received CAN frames matching the added filter(s) are printed to the shell. A few examples are shown below:
186
187.. code-block:: console
188
189   # Dev Flags    ID   Size  Data bytes
190   can0  --       010   [8]  01 02 03 04 05 06 07 08
191   can0  B-       010  [08]  01 02 03 04 05 06 07 08
192   can0  BP       010  [03]  01 aa bb
193   can0  --  00000010   [0]
194   can0  --       010   [1]  20
195   can0  --       010   [8]  remote transmission request
196
197The columns have the following meaning:
198
199* Dev
200
201  * Name of the device receiving the frame.
202
203* Flags
204
205  * ``B``: The frame has the CAN FD Baud Rate Switch (BRS) flag set.
206  * ``P``: The frame has the CAN FD Error State Indicator (ESI) flag set. The transmitting node is
207    in error-passive state.
208  * ``-``: Unset flag.
209
210* ID
211
212  * ``010``: The standard (11-bit) CAN ID of the frame in hexadecimal format, here 10h.
213  * ``00000010``: The extended (29-bit) CAN ID of the frame in hexadecimal format, here 10h.
214
215* Size
216
217  * ``[8]``: The number of frame data bytes in decimal format, here a classic CAN frame with 8 data
218    bytes.
219  * ``[08]``: The number of frame data bytes in decimal format, here a CAN FD frame with 8 data
220    bytes.
221
222* Data bytes
223
224  * ``01 02 03 04 05 06 07 08``: The frame data bytes in hexadecimal format, here the numbers from 1
225    through 8.
226  * ``remote transmission request``: The frame is a Remote Transmission Request (RTR) frame and thus
227    carries no data bytes.
228
229.. tip::
230   If :kconfig:option:`CONFIG_CAN_RX_TIMESTAMP` is enabled, each line will be prepended with a
231   timestamp from the free-running timestamp counter in the CAN controller.
232
233Configured CAN RX filters can be removed again using the ``can filter remove`` subcommand as shown
234below. The filter ID is the ID returned by the ``can filter add`` subcommand (0 in the example
235below).
236
237.. code-block:: console
238
239   uart:~$ can filter remove can@0 0
240   removing filter with ID 0
241
242Sending
243*******
244
245CAN frames can be queued for transmission using the ``can send`` subcommand as shown below. The
246subcommand accepts a CAN ID in hexadecimal format and optionally a number of data bytes, also
247specified in hexadecimal. Refer to the interactive help output for this subcommand for further
248details on the supported arguments.
249
250.. code-block:: console
251
252   uart:~$ can send can@0 010 1 2 3 4 5 6 7 8
253   enqueuing CAN frame #2 with standard (11-bit) CAN ID 0x010, RTR 0, CAN FD 0, BRS 0, DLC 8
254   CAN frame #2 successfully sent
255
256Bus Recovery
257************
258
259The ``can recover`` subcommand can be used for initiating manual recovery from a CAN bus-off event
260as shown below:
261
262.. code-block:: console
263
264   uart:~$ can recover can@0
265   recovering, no timeout
266
267The subcommand accepts an optional bus recovery timeout in milliseconds. If no timeout is specified,
268the command will wait indefinitely for the bus recovery to succeed.
269
270.. note::
271   The ``recover`` subcommand is only available if :kconfig:option:`CONFIG_CAN_MANUAL_RECOVERY_MODE`
272   is enabled.
273