CAN Shell

Overview

The CAN shell provides a can command with a set of subcommands for the shell module. It allows for testing and exploring the CAN Controller 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 Kconfig options must be enabled:

The following Kconfig options enable additional subcommands and features of the can command:

For example, building the Hello World sample for the FRDM-K64F with the CAN shell and CAN statistics enabled:

# From the root of the zephyr repository
west build -b frdm_k64f samples/hello_world -- -DCONFIG_SHELL=y -DCONFIG_CAN=y -DCONFIG_CAN_SHELL=y -DCONFIG_STATS=y -DCONFIG_CAN_STATS=y

See the shell documentation for general instructions on how to connect and interact with the shell. The CAN shell comes with built-in help (unless 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 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 mode, current state, error counters, timing limits, and more:

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
mode:            normal
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
transceiver:     passive/none
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 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 bitrate, sample-point, bitrate-data, and sample-point-data 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.

uart:~$ can bitrate can@0 125000
setting bitrate to 125000 bps

If 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.

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.

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.

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:

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.

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:

# Dev Flags    ID   Size  Data bytes
can0  --       010   [8]  01 02 03 04 05 06 07 08
can0  B-       010  [08]  01 02 03 04 05 06 07 08
can0  BP       010  [03]  01 aa bb
can0  --  00000010   [0]
can0  --       010   [1]  20
can0  --       010   [8]  remote transmission request

The columns have the following meaning:

  • Dev

    • Name of the device receiving the frame.

  • 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 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).

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.

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 manual recovery from a CAN bus-off event as shown below:

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 CONFIG_CAN_MANUAL_RECOVERY_MODE is enabled.