doc: hardware: peripherals: can: add CAN shell documentation
Add documentation for the CAN shell module. Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
This commit is contained in:
Henrik Brix Andersen
Carles Cufí
parent
5752a8f3be
commit
7940c728ab
|
|
@ -8,3 +8,4 @@ Controller Area Network (CAN)
|
|||
|
||||
controller.rst
|
||||
transceiver.rst
|
||||
shell.rst
|
||||
|
|
|
|||
266
doc/hardware/peripherals/can/shell.rst
Normal file
266
doc/hardware/peripherals/can/shell.rst
Normal file
|
|
@ -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 <shell_api>`
|
||||
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 <kconfig>` options must be enabled:
|
||||
|
||||
* :kconfig:option:`CONFIG_SHELL`
|
||||
* :kconfig:option:`CONFIG_CAN`
|
||||
* :kconfig:option:`CONFIG_CAN_SHELL`
|
||||
|
||||
The following :ref:`Kconfig <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 <shell_api>` 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.
|
||||
Loading…
Reference in a new issue