> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CAN

export const tdA = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "left",
  verticalAlign: "top"
};
export const thAeq = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "center",
  backgroundColor: "#f5f5f5",
  fontWeight: "600",
  color: "#333"
};
export const tblA = {
  borderCollapse: "collapse",
  width: "100%",
  fontSize: "14px",
  tableLayout: "fixed"
};

Controller area network (CAN) is a message-based serial protocol. The terms CAN and CAN bus are used in the same context. The advantages of CAN are as follows:

* Uses CSMA/CD method and bitwise contention to sense the bus at the bit-level and transmit the message.
* Each message is assigned a priority. Messages with the highest priority always control the bus arbitration. Since arbitration is based on bits, there are dominant and recessive bit levels.
* Any node can transmit at any time, no primary-secondary nodes.
* All the data is transmitted through two (differential pair) lines: CAN\_H and CAN\_L line.
* CAN nodes are synchronized using bit-synchronization where each bit time is divided in to four segments of time quanta.
* Facilitates communication between multiple nodes through a message-based protocol, eliminating the need for extensive wiring.
* Ensures data security with error management including detection, signaling, and correction.

<Note>
  **Note**

  * CAN is enabled by default in QCS6490 and QCS5430.
  * Dragonwing IQ-9075, Dragonwing IQ-8275, and Dragonwing IQ-615 don't support CAN.
</Note>

## **CAN features**

The CAN protocol supports the following features.

* Multicontroller priority-based bus access
* Nondestructive content-based arbitration
* Broadcast through all-frame transfer
* Multicast frame transfer by acceptance filtering
* Remote data request
* Configuration flexibility
* Network-wide data consistency
* Error detection and error signaling
* Automatically retransmits frames that lose arbitration, lack acknowledgment, or encounter errors during transmission
* Identifies differences between temporary node errors and permanent node failures, and the automatic deactivation of faulty nodes

## **CAN architecture**

The MCP2517 is an external configurable CAN controller, which can be accessed through the SPI line. The SPI interface supports up to 20 MHz with support for Mode0,1. The controller is connected to a QUP block with SE3 configured by a 4-pin SPI operation. The SPI controller is connected to a transceiver (MCP2561xxx) which connects to the CAN bus. Power input to the SPI controller and the CAN transceiver is through the SoC.

<Frame>
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/CAN_architecture.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=a24dcd27e1675ab5ca42072960783e6c" alt="CAN architecture" width="766" height="274" data-path="System/Interfaces/images/CAN_architecture.png" />
</Frame>

<p align="center"><strong>Figure : CAN architecture</strong></p>

The user application communicates with the network interface provided by the SocketCAN. The software driver is a client of the SPI core module in Linux, to which the QUP\_SPI driver is registered with. The actual hardware is connected through the SPI pins.

<Frame>
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/CAN_software_stack.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=b16c0bf876440eab9017a622e475f37d" alt="CAN software stack" width="670" height="666" data-path="System/Interfaces/images/CAN_software_stack.png" />
</Frame>

<p align="center"><strong>Figure : CAN software stack</strong></p>

## **CAN APIs**

For CAN public APIs, see [https://www.kernel.org/doc/Documentation/networking/can.txt](https://www.kernel.org/doc/Documentation/networking/can.txt).

## **CAN samples and tools**

The SocketCAN user space utilities and tools to display, record, generate, and replay the CAN traffic are listed in the following table.

**Table :**

**SocketCAN utilities**

<table style={tblA}>
  <thead>
    <tr>
      <th style={thAeq}>Utility</th>
      <th style={thAeq}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={tdA}>`candump`</td>
      <td style={tdA}>To display, filter and log CAN data to files.</td>
    </tr>

    <tr>
      <td style={tdA}>`canplayer`</td>
      <td style={tdA}>To replay CAN log files.</td>
    </tr>

    <tr>
      <td style={tdA}>`cansend`</td>
      <td style={tdA}>To send a single frame.</td>
    </tr>

    <tr>
      <td style={tdA}>`cangen`</td>
      <td style={tdA}>To generate (random) CAN traffic.</td>
    </tr>

    <tr>
      <td style={tdA}>`cansniffer`</td>
      <td style={tdA}>To display CAN data content differences (just 11‑bit CAN IDs).</td>
    </tr>
  </tbody>
</table>

To download CAN utilities, see [https://github.com/linux-can/can-utils](https://github.com/linux-can/can-utils).

For information about CAN driver files, see `kernel/drivers/net/can/spi/mcp251xfd/mcp251xfd-core.c`.

### **CAN analyzer - PCAN-USB FD**

The PCAN-USB FD is a versatile CAN packet/message sniffer that can operate as a node on any CAN bus, supporting flexible data rates. It can be used to sniff and send CAN packets on a host machine over USB. The key features are as follows:

* PCAN-View GUI tool
  * Provides easy ways to sniff and send CAN packets as per-user needs.
  * Monitors and debugs CAN packets during development and testing.
* PCAN-USB FD interface
  * Enables a simple connection to CAN FD and CAN networks.
  * Compact plastic casing suitable for mobile applications.
  * Galvanic isolation of up to 500 V decouples the PC from the CAN bus.
* CAN FD standard
  * Characterized by higher bandwidth for data transfer.
  * Allows transmission of up to 64 data bytes per CAN FD frame (instead of 8).
  * Supports bit rates up to 12 Mbit/s.
  * Downward compatible with the CAN 2.0 standard.
  * CAN FD nodes can be inserted into existing CAN networks without CAN FD extensions.

**Hardware setup**

1. Connect to the DB9 connector.
   * The PCAN has a DB9 connector on which any standard DB9 connector can be plugged in.
2. Connect to the Qualcomm device.
   * Pull out the CAN\_H, CAN\_L, and GND lines.
   * Connect these lines to the two terminal-resistors of 120 Ω.
3. Connect CAN\_H, CAN\_L, and Ground.

<Frame>
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/CAN_connections.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=62cb3bdfab142434760210fd9760ebdd" alt="CAN connections" width="696" height="233" data-path="System/Interfaces/images/CAN_connections.png" />
</Frame>

<p align="center"><strong>Figure : CAN connections</strong></p>

4. Connect an external terminating resistor.

<Note>
  **Note**

  The device doesn't have an internal terminating resistor of 120 Ω. This is crucial because some tools provide built-in support for the terminating resistor.
</Note>

<Frame>
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/CAN_Terminating_resistor.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=e29768e344e5981bbc43a0a54b5d1a60" alt="CAN terminating resistor" width="645" height="267" data-path="System/Interfaces/images/CAN_Terminating_resistor.png" />
</Frame>

<p align="center"><strong>Figure : CAN terminating resistor</strong></p>

The following figure shows the connected hardware.

<Frame>
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/CAN_device_connection.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=005cfb4d22c6950e19d78d12ac7b4ce5" alt="CAN USB FD, external resistor, and device connection" width="768" height="498" data-path="System/Interfaces/images/CAN_device_connection.png" />
</Frame>

<p align="center"><strong>Figure : CAN USB FD, external resistor, and device connection</strong></p>

## **Bringup CAN interface**

After the CAN driver is built and loaded into the kernel, the following sequence of commands sends data to identify if the CAN node is up. A CAN node can be started or stopped using the commands listed in the following table.

<Note>
  **Note**

  All the network devices use `ifconfig -a`.
</Note>

**Table :**

**CAN commands**

<table style={tblA}>
  <thead>
    <tr>
      <th style={thAeq}>Instruction</th>
      <th style={thAeq}>Command</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={tdA}>Check for the can node number</td>
      <td style={tdA}>`ifconfig -a`</td>
    </tr>

    <tr>
      <td style={tdA}>Set a bit rate of 125 kbps</td>
      <td style={tdA}>`ip link set can0 up type can bitrate 125000`</td>
    </tr>

    <tr>
      <td style={tdA}>Start CAN</td>
      <td style={tdA}>`ip link set can0 up`</td>
    </tr>

    <tr>
      <td style={tdA}>Stop CAN</td>
      <td style={tdA}>`ip link set can0 down`</td>
    </tr>

    <tr>
      <td style={tdA}>Check the CAN configuration</td>
      <td style={tdA}>`ip -details link show can0`</td>
    </tr>

    <tr>
      <td style={tdA}>CAN internal loopback</td>
      <td style={tdA}>`ip link set can0 up type can bitrate 500000 loopback on`</td>
    </tr>

    <tr>
      <td style={tdA}>CAN FD internal loopback</td>
      <td style={tdA}>`ip link set can0 up type can bitrate 1000000 dbitrate 5000000 fd on loopback on`</td>
    </tr>

    <tr>
      <td style={tdA}>Send CAN FD frame</td>
      <td style={tdA}>`cansend can0 213##311223344`</td>
    </tr>
  </tbody>
</table>

To start any CAN node, the bit rate for the bus must be defined, or configured if the bus-rate is already available. This configuration ensures that the CAN node is up and active. For more details about CAN utilities, see [https://manpages.debian.org/testing/can-utils/index.html](https://manpages.debian.org/testing/can-utils/index.html).

### **Send and receive data**

Some utilities are available in the `CAN-Utils` file. SocketCAN enables CAN nodes for sending and receiving data. SocketCAN APIs are also used for custom applications.

* Send data with 11‑bit ID
  ```text theme={null}
  cansend can0 7AF#11.22.33.44.55.66.aa.ff
  ```
* Send data with 29‑bit ID
  ```text theme={null}
  cansend can0 111FFFFF#aa.00.cc.aa.33.61.aa.ab
  ```
* View the current incoming data on can0 node
  ```text theme={null}
  candump can0
  ```

## **Configure CAN interface**

SocketCAN is an implementation of the CAN protocol for Linux. SocketCAN uses the Berkeley socket API, the Linux network stack and implements the CAN device drivers as network interfaces. The CAN socket API has been designed as similar as possible to the TCP/IP protocols to allow users, familiar with network programming, easily learn how to use CAN sockets.

### **Initialize hardware**

The driver initializes and configures the underlying hardware block. The initialization occurs after the `driver's _probe()` function is called.

```text theme={null}
static struct spi_driver mcp251xfd_driver = {
    .driver = {
        .name = DEVICE_NAME,
        .pm = &mcp251xfd_pm_ops,
        .of_match_table = mcp251xfd_of_match,
    },
    .probe = mcp251xfd_probe,
    .remove = mcp251xfd_remove,
    .id_table = mcp251xfd_id_table,
};
 
static int mcp251xfd_probe(struct spi_device *spi)
{
    struct net_device *ndev;
    struct mcp251xfd_priv *priv;
[..]
ndev = alloc_candev(sizeof(struct mcp251xfd_priv),
                MCP251XFD_TX_OBJ_NUM_MAX);
    if (!ndev)
        return -ENOMEM;
 
    SET_NETDEV_DEV(ndev, &spi->dev); // The SPI node is set as the parent node to the network device. 
 
    ndev->netdev_ops = &mcp251xfd_netdev_ops;
[..]
    err = mcp251xfd_register(priv);
};
```

## **Debug CAN issues**

CAN issues can be debugged using the `ftrace` tool. The MCP2517 driver supports the `dev_coredump()` API.

## **CAN examples**

For CAN examples, see [https://github.com/linux-can/can-utils/blob/master/README.md](https://github.com/linux-can/can-utils/blob/master/README.md).