diff --git a/doc/hardware/peripherals/can/index.rst b/doc/hardware/peripherals/can/index.rst index 6e96fb15cb..c605bdd030 100644 --- a/doc/hardware/peripherals/can/index.rst +++ b/doc/hardware/peripherals/can/index.rst @@ -8,3 +8,4 @@ Controller Area Network (CAN) controller.rst transceiver.rst + shell.rst diff --git a/doc/hardware/peripherals/can/shell.rst b/doc/hardware/peripherals/can/shell.rst new file mode 100644 index 0000000000..cfd016843d --- /dev/null +++ b/doc/hardware/peripherals/can/shell.rst @@ -0,0 +1,266 @@ +.. _can_shell: + +CAN Shell +######### + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +The CAN shell provides a ``can`` command with a set of subcommands for the :ref:`shell ` +module. It allows for testing and exploring the :ref:`can_api` driver API through an interactive +interface without having to write a dedicated application. The CAN shell can also be enabled in +existing applications to aid in interactive debugging of CAN issues. + +The CAN shell provides access to most CAN controller features, including inspection, configuration, +sending and receiving of CAN frames, and bus recovery. + +In order to enable the CAN shell, the following :ref:`Kconfig ` options must be enabled: + +* :kconfig:option:`CONFIG_SHELL` +* :kconfig:option:`CONFIG_CAN` +* :kconfig:option:`CONFIG_CAN_SHELL` + +The following :ref:`Kconfig ` options enable additional subcommands and features of the +``can`` command: + +* :kconfig:option:`CONFIG_CAN_FD_MODE` enables CAN FD specific subcommands (e.g. for setting the + timing for the CAN FD data phase). +* :kconfig:option:`CONFIG_CAN_RX_TIMESTAMP` enables printing of timestamps for received CAN frames. +* :kconfig:option:`CONFIG_CAN_STATS` enables printing of various statistics for the CAN controller + in the ``can show`` subcommand. This depends on :kconfig:option:`CONFIG_STATS` being enabled as + well. +* :kconfig:option:`CONFIG_CAN_AUTO_BUS_OFF_RECOVERY` enables the ``can recover`` subcommand when + disabled. + +For example, building the :ref:`hello_world` sample for the :ref:`frdm_k64f` with the CAN shell and +CAN statistics enabled: + +.. zephyr-app-commands:: + :zephyr-app: samples/hello_world + :board: frdm_k64f + :gen-args: -DCONFIG_SHELL=y -DCONFIG_CAN=y -DCONFIG_CAN_SHELL=y -DCONFIG_STATS=y -DCONFIG_CAN_STATS=y + :goals: build + +See the :ref:`shell ` documentation for general instructions on how to connect and +interact with the shell. The CAN shell comes with built-in help (unless +:kconfig:option:`CONFIG_SHELL_HELP` is disabled). The built-in help messages can be printed by +passing ``-h`` or ``--help`` to the ``can`` command or any of its subcommands. All subcommands also +support tab-completion of their arguments. + +.. tip:: + All of the CAN shell subcommands take the name of a CAN controller as their first argument, which + also supports tab-completion. A list of all devices available can be obtained using the ``device + list`` shell command when :kconfig:option:`CONFIG_DEVICE_SHELL` is enabled. The examples below + all use the device name ``can@0``. + +Inspection +********** + +The properties of a given CAN controller can be inspected using the ``can show`` subcommand as shown +below. The properties include the core CAN clock rate, the maximum supported bitrate, the number of +RX filters supported, capabilities, current state, error counters, timing limits, and more: + +.. code-block:: console + + uart:~$ can show can@0 + core clock: 144000000 Hz + max bitrate: 5000000 bps + max std filters: 15 + max ext filters: 15 + capabilities: normal loopback listen-only fd + state: stopped + rx errors: 0 + tx errors: 0 + timing: sjw 1..128, prop_seg 0..0, phase_seg1 2..256, phase_seg2 2..128, prescaler 1..512 + timing data: sjw 1..16, prop_seg 0..0, phase_seg1 1..32, phase_seg2 1..16, prescaler 1..32 + statistics: + bit errors: 0 + bit0 errors: 0 + bit1 errors: 0 + stuff errors: 0 + crc errors: 0 + form errors: 0 + ack errors: 0 + rx overruns: 0 + +.. note:: + The statistics are only printed if :kconfig:option:`CONFIG_CAN_STATS` is enabled. + +Configuration +************* + +The CAN shell allows for configuring the CAN controller mode and timing, along with starting and +stopping the processing of CAN frames. + +.. note:: + The CAN controller mode and timing can only be changed while the CAN controller is stopped, which + is the initial setting upon boot-up. The initial CAN controller mode is set to ``normal`` and the + initial timing is set according to the ``bus-speed``, ``sample-point``, ``bus-speed-data``, and + ``sample-point-data`` :ref:`devicetree` properties. + +Timing +====== + +The classic CAN bitrate/CAN FD arbitration phase bitrate can be configured using the ``can bitrate`` +subcommand as shown below. The bitrate is specified in bits per second. + +.. code-block:: console + + uart:~$ can bitrate can@0 125000 + setting bitrate to 125000 bps + +If :kconfig:option:`CONFIG_CAN_FD_MODE` is enabled, the data phase bitrate can be configured using +the ``can dbitrate`` subcommand as shown below. The bitrate is specified in bits per second. + +.. code-block:: console + + uart:~$ can dbitrate can@0 1000000 + setting data bitrate to 1000000 bps + +Both of these subcommands allow specifying an optional sample point in per mille and a +(Re)Synchronization Jump Width (SJW) in Time Quanta as positional arguments. Refer to the +interactive help of the subcommands for more details. + +It is also possible to configure the raw bit timing using the ``can timing`` and ``can dtiming`` +subcommands. Refer to the interactive help output for these subcommands for details on the required +arguments. + +Mode +==== + +The CAN shell allows for setting the mode of the CAN controller using the ``can mode`` +subcommand. An example for enabling loopback mode is shown below. + +.. code-block:: console + + uart:~$ can mode can@0 loopback + setting mode 0x00000001 + +The subcommand accepts multiple modes given on the same command line (e.g. ``can mode can@0 fd +loopback`` for setting CAN FD and loopback mode). Vendor-specific modes can be specified in +hexadecimal. + +Starting and Stopping +===================== + +After the timing and mode has been configured as needed, the CAN controller can be started using the +``can start`` subcommand as shown below. This will enable reception and transmission of CAN frames. + +.. code-block:: console + + uart:~$ can start can@0 + starting can@0 + +Prior to reconfiguring the timing or mode, the CAN controller needs to be stopped using the ``can +stop`` subcommand as shown below: + +.. code-block:: console + + uart:~$ can stop can@0 + stopping can@0 + +Receiving +********* + +In order to receive CAN frames, one or more CAN RX filters need to be configured. CAN RX filters are +added using the ``can filter add`` subcommand as shown below. The subcommand accepts a CAN ID in +hexadecimal format along with an optional CAN ID mask, also in hexadecimal format, for setting which +bits in the CAN ID are to be matched. Refer to the interactive help output for this subcommand for +further details on the supported arguments. + +.. code-block:: console + + uart:~$ can filter add can@0 010 + adding filter with standard (11-bit) CAN ID 0x010, CAN ID mask 0x7ff, data frames 1, RTR frames 0, CAN FD frames 0 + filter ID: 0 + +The filter ID (0 in the example above) returned is to be used when removing the CAN RX filter. + +Received CAN frames matching the added filter(s) are printed to the shell. A few examples are shown below: + +.. code-block:: console + + # Flags ID Size Data bytes + -- 010 [8] 01 02 03 04 05 06 07 08 + B- 010 [08] 01 02 03 04 05 06 07 08 + BP 010 [03] 01 aa bb + -- 00000010 [0] + -- 010 [1] 20 + -- 010 [8] remote transmission request + +The columns have the following meaning: + +* Flags + + * ``B``: The frame has the CAN FD Baud Rate Switch (BRS) flag set. + * ``P``: The frame has the CAN FD Error State Indicator (ESI) flag set. The transmitting node is + in error-passive state. + * ``-``: Unset flag. + +* ID + + * ``010``: The standard (11-bit) CAN ID of the frame in hexadecimal format, here 10h. + * ``00000010``: The extended (29-bit) CAN ID of the frame in hexadecimal format, here 10h. + +* Size + + * ``[8]``: The number of frame data bytes in decimal format, here a classic CAN frame with 8 data + bytes. + * ``[08]``: The number of frame data bytes in decimal format, here a CAN FD frame with 8 data + bytes. + +* Data bytes + + * ``01 02 03 04 05 06 07 08``: The frame data bytes in hexadecimal format, here the numbers from 1 + through 8. + * ``remote transmission request``: The frame is a Remote Transmission Request (RTR) frame and thus + carries no data bytes. + +.. tip:: + If :kconfig:option:`CONFIG_CAN_RX_TIMESTAMP` is enabled, each line will be prepended with a + timestamp from the free-running timestamp counter in the CAN controller. + +Configured CAN RX filters can be removed again using the ``can filter remove`` subcommand as shown +below. The filter ID is the ID returned by the ``can filter add`` subcommand (0 in the example +below). + +.. code-block:: console + + uart:~$ can filter remove can@0 0 + removing filter with ID 0 + +Sending +******* + +CAN frames can be queued for transmission using the ``can send`` subcommand as shown below. The +subcommand accepts a CAN ID in hexadecimal format and optionally a number of data bytes, also +specified in hexadecimal. Refer to the interactive help output for this subcommand for further +details on the supported arguments. + +.. code-block:: console + + uart:~$ can send can@0 010 1 2 3 4 5 6 7 8 + enqueuing CAN frame #2 with standard (11-bit) CAN ID 0x010, RTR 0, CAN FD 0, BRS 0, DLC 8 + CAN frame #2 successfully sent + +Bus Recovery +************ + +The ``can recover`` subcommand can be used for initiating recovery from a CAN bus-off event as shown +below: + +.. code-block:: console + + uart:~$ can recover can@0 + recovering, no timeout + +The subcommand accepts an optional bus recovery timeout in milliseconds. If no timeout is specified, +the command will wait indefinitely for the bus recovery to succeed. + +.. note:: + The ``recover`` subcommand is only available if + :kconfig:option:`CONFIG_CAN_AUTO_BUS_OFF_RECOVERY` is disabled.