Universal Resource Identifiers COM2002X (ARCNET) Protocol navigation bar

CAN Protocol

The Controller Area Network or CAN protocol supports sending and receiving data over CAN bus.

Syntax

can://localhost:port?option=value,... % Use CAN channel "port" with specified options
    

Description

The CAN protocol supports sending and receiving data over CAN bus. It is identified by using can as the protocol name in a URI. Appropriate hardware supporting CAN must be present on the system using the protocol.

The hostname in the URI is ignored, if specified. The port is an unsigned integer indicating which CAN port to use. Port 0 is the first CAN port in the system.

The options for the CAN protocol are listed below are the standard options. Some of the options may not be available on some platforms.

CAN bus is a multi-master serial bus standard commonly used in automotive. It is an asynchronous protocol over a two-wire (CANH and CANL) differential wired-AND bus. Multiple devices may be connected to the same bus.

Each message or "frame" sent on the CAN bus contains an identifier (11-bit for standard frames or 29-bit for extended frames) and data. All devices on the bus receive the frame and decide based on the identifier whether to process the data.

The identifier for a particular message is specified by setting the STREAM_PROPERTY_MESSAGE_ID integer property of the stream using the stream_set_integer_property function. The next send operation will then use that message identifier. If the identifier is larger than 11 bits than the extended frame format will be used for the packet, allowing identifiers up to 29 bits.

The identifier of the last received message is retrieved by getting the STREAM_PROPERTY_MESSAGE_ID integer property of the stream using the stream_get_integer_property function.

The CAN protocol can use classical data frames, which support a 0 to 8 byte payload, or it can use CAN FD (flexible data rate) data frames, which support a 0 to 64 byte payload. When using CAN FD, the header and payload are sent at two different baud rates. The payload is transmitted at a faster rate because at that point arbitration, which occurs during the header transmission, is complete and the master now has full control over the bus. To enable the use of CAN FD, set the flexible option to "yes" or "either" in the URI.

The maximum size of the payload is important because it determines how much data is sent in each CAN frame. When communicating between two CAN devices, for instance, a classical data frame can only hold a single 8-byte double value, but a CAN FD frame can hold up to eight double values.

The byte ordering of data may be configured using the byte_order argument of the stream_set_byte_order function, for example.

To read from the CAN bus, the stream_receive function, or one of its variants, may be used to receive data from the stream. The byte ordering is configured using the stream_set_byte_order or stream_set_swap_bytes function.

Writing to the CAN bus

The following table shows the required sequence of events for a typical write transaction.

Step

Operation

Description

1

Stream Set Property

Set the STREAM_PROPERTY_MESSAGE_ID property to the desired message identifier.

2

Stream Write

Write the CAN frame to the bus using the assigned message identifier.

Reading from the CAN bus

The following table shows the required sequence of events for a typical read transaction.

Step

Operation

Description

1

Stream Read

Read a CAN frame from the bus.

2

Stream Get Property

Get the STREAM_PROPERTY_MESSAGE_ID property to retrieve the message identifier of the received CAN frame.

The CAN protocol driver may discard frames depending on the peer option. See the discussion of the peer option below for details. The default option is peer=none.

Handling Multiple Data Types

Sometimes the data read from or written to a slave device involves a combination of different data types. For example, an IMU CAN device may return a uint8 status value, an int8 temperature value and three int16 axis values in a single frame. To read or write multiple data types in a single frame, use the stream_peek or stream_poke functions respectively.

Remote Transmission Requests

To perform a remote transmission request, use the stream_set_boolean_property function to set the STREAM_PROPERTY_CAN_REQUEST property. Subsequent send operations will send a remote transmission request instead of a regular packet. The number of bytes "sent" will determine the number of bytes returned by the remote device. Be sure to turn off the property when a remote transmission request is not being sent.

Error Frames

If an error frame is received, the identifier will have the 0x20000000 bit set and the stream_get_boolean_property function will return true for the STREAM_PROPERTY_CAN_ERROR property. Be sure to turn off the property when an error frame is not being sent.

Limitations

Performance

Warning The performance of the CAN protocol depends on the performance of the underlying CAN device. Be sure to check the capabilities of your underlying hardware. Signal integrity issues also affect the maximum baud rate achievable. For example, at high rates the capacitance of the lines can slow down the signals and limit the baud rate attainable particularly since the CAN protocol uses open-drain differential lines.

QUARC Target Manager

Warning The CAN protocol cannot be used for communicating with the target (via a target URI) because the CAN protocol does not allow multiple connections on the same port. Nor should it be used as a model URI.

Installation Requirements

QCar

Install On the QCar, CAN bus support is not automatically enabled, but must first be configured. First, the necessary kernel drivers must be loaded and then the network interfaces for CAN bus must be set up.

To load the kernel drivers necessary for CAN bus support, execute the following commands in a Terminal window on the QCar:

sudo modprobe can
sudo modprobe can_raw
sudo modprobe mttcan
            

Then to bring up CAN0 for CAN FD with a 500 kHz standard rate and 2 MHz data rate, use the commands:

sudo ip link set can0 type can bitrate 500000 sjw 4 dbitrate 2000000 dsjw 4 fd on berr-reporting on restart-ms 100
sudo ip link set up can0
            

Likewise for CAN1:

sudo ip link set can1 type can bitrate 500000 sjw 4 dbitrate 2000000 dsjw 4 fd on berr-reporting on restart-ms 100
sudo ip link set up can1
            

The CAN interfaces will now be visible when using the ifconfig command, just like other network interfaces.

Options

bufsize

The memsize option determines the size of the send and receive buffer (in bytes) used for CAN bus transactions. This size determines the maximum number of bytes that can be transferred in one send or receive operation. It is not the same as the Stream API's send and receive buffers but is used in interfacing with the low-level drivers that implement the CAN protocol. The default buffer size depends on the underlying CAN device. Setting this option is equivalent to setting both the rcvsize and sndsize options at the same time.

rcvsize

The rcvsize option determines the size of the receive buffer (in bytes) used for CAN bus transactions. This size determines the maximum number of bytes that can be transferred in one receive operation. It is not the same as the Stream API's receive buffers but is used in interfacing with the low-level drivers that implement the CAN protocol. The default buffer size depends on the underlying CAN device.

sndsize

The sndsize option determines the size of the send buffer (in bytes) used for CAN bus transactions. This size determines the maximum number of bytes that can be transferred in one send operation. It is not the same as the Stream API's send buffers but is used in interfacing with the low-level drivers that implement the CAN protocol. The default buffer size depends on the underlying CAN device.

flexible

The flexible option may be set to either "yes", "no" or "either". The values "y" or "1" may also be used instead of "yes". Likewise "n" or "0" may be used instead of "no".

When the flexible option is set to yes then the CAN FD protocol is used, which has the larger maximum 64-byte payload.

When the flexible option is set to no then classical CAN frames are used, which have a maximum 8-byte payload.

If the flexible option is set to either then whether a classic CAN frame or the newer CAN FD frame is used depends on the STREAM_PROPERTY_CAN_FLEXIBLE property. When this property is true then CAN FD frames are used. Otherwise the class CAN frame is used. Use the stream_set_boolean_property function to set this property dynamically.

peer

This option determines how the CAN protocol handles communication with multiple clients or "peers". It may be set to one of four values: none, one, any or manual.

If the peer option is set to none then the CAN protocol only receives frames from the port specified in the URI.

If the peer option is set to one then the CAN protocol driver may receive a frame from any of the CAN interfaces or ports available on the target, but once the first frame has been received, that port will become the "designated peer" and it will only receive frames from that port from then on. Frames from other ports will be silently discarded. If no frame has been received before the first send operation then the QERR_NO_DESIGNATED_PEER error will be returned. Hence, in this case a receive operation should always be done before the first send operation.

If the peer option is set to any then the CAN protocol driver communicates with multiple peers. The last interface or port from which a frame is received is stored as the "designated peer". All subsequent send operations will communicate only with that designated peer. Thus, a receive operation should always be done before the first send operation . Failure to do so will result in a -QERR_NO_DESIGNATED_PEER error. Frames received from other peers will change the designated peer so that subsequent send operations will go to the new peer.

The peer equal to any option is best when clients are connecting from multiple CAN interfaces one at a time. If more than one client connects at the same time then all the clients will be sending frames to the server. The server will receive all the client frames without any problem. However, any data sent from the server to the clients is sent to the client whose frame was received most recently. As the order in which CAN frames arrive is indeterminate, some clients may get starved of data if their CAN frames aren't the last to arrive when the server decides to send data. As a result, the server data received at the clients may look decimated or randomly sampled. Hence, this option is best suited for the situation where clients are either communicating one at a time, or they are not receiving any data from the server.

For client connections established with the Stream Connect block, the initial designated peer is the one specified in the block parameters. However, each frame received changes the designated peer in the same way as it does for server connections when the client has the peer option set to any.

If the peer option is set to manual then the CAN protocol driver communicates with the peer set using the Stream Set Property block and the STREAM_PROPERTY_PEER_ADDRESS string property code. The peer address can be changed at any time to communicate with a new peer.

The format of the address is "hostname:port?device=prefix", much like the URI for CAN. For example, "localhost:0 or localhost:1?device=can".

To retrieve the peer from which a datagram was last received, use the Stream Get Property block and the STREAM_PROPERTY_PEER_ADDRESS string property code.

The default peer is none since it corresponds most closely with the way CAN typically functions.

device

Set this option to the prefix to use for the name of the CAN device. For example, on the QCar the CAN interfaces are named can0 and can1 so the device prefix is "can".

Driver

The driver supporting the CAN protocol is called qrt_can.

Targets

Target

Supported

Comments

QUARC Win32 Target

No

Not currently supported.

QUARC Win64 Target

No

Not currently supported.

QUARC Linux Nvidia Target

Yes

Fully supported.

QUARC Linux QBot Platform Target

No

Not currently supported.

QUARC Linux QCar 2 Target

No

Not currently supported.

QUARC Linux QDrone 2 Target

No

Not currently supported.

QUARC Linux Raspberry Pi 3 Target

No

Not currently supported.

QUARC Linux Raspberry Pi 4 Target

No

Not currently supported.

QUARC Linux RT ARMv7 Target

No

Not currently supported.

QUARC Linux x64 Target

No

Not currently supported.

QUARC Linux DuoVero Target

No

Not currently supported.

QUARC Linux DuoVero 2016 Target

No

Not currently supported.

QUARC Linux Verdex Target

No

Not currently supported.

QUARC QNX x86 Target

No

Last fully supported in QUARC 2018.

See Also

 

navigation bar