.. include:: ../substitutions.rst
.. include:: stdout.rst

CAN
===

The i.MX RT1170 processor includes three FlexCAN FD controllers (``flexcan1``, ``flexcan2``, and ``flexcan3``). In the current |release-name| release, only ``flexcan3`` (``can@40c3c000``) is enabled and exposed on the |product| module, routed to connector X20 on the |product-cb| carrier board. You can inspect and exercise this device directly from the Zephyr shell using the built-in ``can`` commands, without writing any application code.

.. note:: The maximum supported CAN data rate is currently 500 kbit/s.

For detailed hardware-level information, refer to the *7.1 FlexCAN* chapter in the |hw-manual-link|.

Requirements
------------

* Two sets of |product-cb| carrier board

or (to test CAN from a host PC)

* DB9 Male to RS232 Female Cable (Included in development kit)

* CAN Cable

   * `PCAN Cable 2 <https://phytools.com/products/pcan-cable-2-w-120-ohm-termination-1?variant=46663909081324&currency=USD>`_

* CAN to USB Adapter

   * `PCAN-USB Adapter <https://phytools.com/collections/usb-interfaces/products/pcan-usb-adapter>`_
   * `candleLight FD <https://shop.linux-automation.com/catalogue/candlelightfd_3/>`_

Shell Usage
-----------

The examples below use two |product-cb| carrier boards with their CAN transceivers connected together via connector X20, referred to as Device A (sender) and Device B (receiver).

Run ``can`` without arguments to list the available subcommands:

.. code-block:: console
   :substitutions:

   |target-prompt| can

.. code-block:: none
   :caption: Expected Output

   can - CAN controller commands
   Subcommands:
     start     : Start CAN controller
                 Usage: start <device>
     stop      : Stop CAN controller
                 Usage: stop <device>
     show      : Show CAN controller information
                 Usage: show <device>
     bitrate   : Set CAN controller bitrate (sample point and SJW optional)
                 Usage: bitrate <device> <bitrate> [sample point] [sjw]
     dbitrate  : Set CAN controller data phase bitrate (sample point and SJW
                 optional)
                 Usage: dbitrate <device> <data phase bitrate> [sample point] [sjw]
     timing    : Set CAN controller timing
                 Usage: timing <device> <sjw> <prop_seg> <phase_seg1> <phase_seg2>
                        <prescaler>
     dtiming   : Set CAN controller data phase timing
                 Usage: dtiming <device> <sjw> <prop_seg> <phase_seg1> <phase_seg2>
                        <prescaler>
     mode      : Set CAN controller mode
                 Usage: mode <device> <mode> [mode] [mode] [...]
     send      : Enqueue a CAN frame for sending
                 Usage: send <device> [-e] [-r] [-f] [-b] <CAN ID> [data] [...]
                        -e  use extended (29-bit) CAN ID
                        -r  send Remote Transmission Request (RTR) frame
                        -f  use CAN FD frame format
                        -b  use CAN FD Bit Rate Switching (BRS)
     filter    : CAN rx filter commands
                 Usage: filter <add|remove> <device> ...
     dump      : Dump all CAN controller RX frames
                 Usage: dump <device>

Starting the CAN Controller
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before using a CAN controller, start it on both boards:

.. code-block:: console
   :substitutions:

   |target-prompt| can start can@40c3c000

.. code-block:: none
   :caption: Expected Output

   uart:~$ can start can@40c3c000
   starting can@40c3c000

Checking Controller Status
~~~~~~~~~~~~~~~~~~~~~~~~~~~

To inspect a controller's current configuration and state:

.. code-block:: console
   :substitutions:

   |target-prompt| can show can@40c3c000

.. code-block:: none
   :caption: Expected Output

   core clock:      24000000 Hz
   max bitrate:     5000000 bps
   max std filters: 5
   max ext filters: 5
   capabilities:    normal loopback listen-only fd triple-sampling
   mode:            normal
   state:           error-active
   rx errors:       0
   tx errors:       0
   timing:          sjw 1..32, prop_seg 1..64, phase_seg1 1..32, phase_seg2 2..32, prescaler 1..1024
   timing data:     sjw 1..8, prop_seg 1..31, phase_seg1 1..8, phase_seg2 2..8, prescaler 1..1024
   transceiver:     can-phy0

Sending and Receiving Frames
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Device A, send a CAN frame with standard ID ``0x000`` and data bytes ``12 34 56 78``:

.. code-block:: console
   :substitutions:

   |target-prompt| can send can@40c3c000 0 12 34 56 78

.. code-block:: none
   :caption: Expected Output (Device A)

   uart:~$ can send can@40c3c000 0 12 34 56 78
   enqueuing CAN frame #1 with standard (11-bit) CAN ID 0x000, RTR 0, CAN FD 0, BRS 0, DLC 4
   CAN frame #1 successfully sent

On Device B, dump incoming frames to see it arrive:

.. code-block:: console
   :substitutions:

   |target-prompt| can dump can@40c3c000

.. code-block:: none
   :caption: Expected Output (Device B)

   uart:~$ can dump can@40c3c000
   dumping CAN RX frames on device can@40c3c000, press Ctrl+C to exit
   can@40c3c000  --       000   [4]  12 34 56 78

.. note:: Please refer to the CAN reference documents for other products to learn how to test using a host PC.

.. include:: ../../common/support-disclaimer-us.rst