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