Receiving and Sending Data

CAN Bus Sensor Module workflow

Initialization

Initialization of the CAN bus sensor is achieved as follows:

dwSensorParams params{};
params.protocol = "can.socket";
params.parameters = "device=can0";
 
dwSensorHandle_t canSensor;
dwSAL_createSensor(&canSensor, params, ...);

Protocol

The dwSensorParams.protocol expects one of the following can interfaces:

• can.socket interface for system CAN bus.
• can.virtual interface for reading CAN data from binary logs.

Sensor parameters

The dwSensorParams.parameters accepts the following parameters:

For all:

filter=id:mask[+id:mask]:

• filter is a string of + seperated filters
• id is a hex value
• mask is a hex value

Example: filter=123:FFF+60A:FFF

See the Setting message filters section to see how these values are used.

When using can.socket:

device=can0[,fifo-size=1024]

• device CAN device interface, usually canx, x starting from 0
  • on Linux, use ifconfig to list available CAN interfaces
  • on QNX, use pidin a | grep nvcan to list available CAN interfaces
• fifo-size size of internal buffer, in number of dwCANMessage stored.
• discard-threshold the timestamp of CAN data who is older than current timestamp by threshold will be discarded.
  • only apply on QNX(CANQnx)
• read-number data size to be read from driver buffer in one syscall, default number is 256
  • only apply on QNX(CANQnx)
• do-not-send disables send functionality when set to true.

When using can.simulator:

Identical parameters to can.socket.

When using can.virtual:

file=/path/to/file.can[,create_seek,default_timeout_us,time-offset=0]

• file path to CAN bus recording
• create_seek create seek table
• default_timeout_us period after which sensor times out
• time-offset offset applied to CAN messages timestamps

The CAN buses are setup with CAN FD if supported. If not supported sending and receiving CAN FD messages will fail.

Starting, stopping and releasing sensor

The CAN bus sensor can be started, stopped and released as follows:

dwSensor_start(canSensor);
dwSensor_stop(canSensor);
dwSAL_releaseSensor(&canSensor);

Reading CAN messages

CAN messages can be read from the bus as follows:

dwCANMessage msg{};
dwStatus status = dwSensorCAN_readMessage(&msg, 10000, canSensor);

This will populate a dwCANMessage structure with the next CAN message received on the bus, in this example waiting up to 10000us, or 10ms, for a message to arrive. Timeout can be set to DW_TIMEOUT_INFINITE to indicate infinite waiting until new message arrives, or 0 to immediately return and only read messages already received. The dwCANMessage structure can hold up to 64 bytes to accommodate CAN FD messages.

To only read messages available in the internal queue, without reading new messages on the CAN bus, the dwSensorCAN_popMessage() method can be used. Together with dwSensorCAN_processRawData(), raw binary CAN data can be read and parsed in dwCANMessage format, see Reading CAN Messages from Raw Data (Binary).

Sending CAN messages

CAN messages can be sent on the bus as follows:

dwCANMessage msg{};
 
msg.id = 0x123;
msg.data[0] = 0xFF;
msg.size = 1;
msg.timestamp = 0;
 
dwSensorCAN_sendMessage(&msg, 10000, canSensor);

This sends a message over the CAN bus within a specified timeout. A message is guaranteed to have been sent when this method returns DW_SUCCESS. The method can block for up-to the specified amount of time if a bus is blocked or previous dwSensorCAN_readMessage() operation has not yet finished.

If the msg.size value is from 9 - 64, then the message will be sent as a CAN FD message.

Setting message filters

CAN messages be filtered by ID as follows:

uint32_t ids[2] = {0x100, 0x6AB};
uint32_t masks[2] = {0xF00, 0xFFF};
 
dwSensorCAN_setMessageFilter(&ids, &masks, 2, canSensor);

This function takes an array of IDs and an array of masks to setup filters. Once the filters are set, only messages with IDs matching the filters will be read. Each call to the above will reset previously set filters. To reset all filtering, call the above with 0 as number of filters.

Internally, only messages that meet the following condition for at least one filter are read:

(messageID & mask) == (id & mask)

Masks are optional; when passing NULL, a default mask of 1FFFFFFF is used.

Setting hardware timestamping

The dwSensorCAN_setUseHwTimestamps() function allows the user to enable or disable hardware timestamping of messages on compatible CAN Bus devices. By default, hardware timestamping is enabled if available, but can be turned off if the default behavior is not working properly with the current hardware stack.

The dwSensorCAN_readMessage() function reads the next available CAN message with a given timeout. The function call is blocking, until a CAN message is available or the timeout is exceeded. Filters can be set with dwSensorCAN_setMessageFilter() so that only specific messages are read from the bus. Messages can be sent with dwSensorCAN_sendMessage().

The dwCANMessage structure holds a CAN message, consisting of a timestamp, an ID, message data (payload) and size. The CAN bus module supports the extended CAN frame format.

Example

The following code shows the general structure of a program setting up CAN message filters and receiving/sending messages on the bus. Only messages with IDs 0x100-0x1FF and 0x6AB will be read.

dwSensorParams params{};
params.protocol = "can.socket";
params.parameters = "device=can0";
 
dwSensorHandle_t canSensor;
dwSAL_createSensor(&canSensor, params, ...);
 
uint32_t ids[2] = {0x100, 0x6AB};
uint32_t masks[2] = {0xF00, 0xFFF};
 
dwSensorCAN_setMessageFilter(&ids, &masks, 2, canSensor);
 
dwSensor_start(canSensor);
 
while(loop)
{
    dwCANMessage msg{};
 
    // read all messages until internal queue is empty
    while(dwSensorCAN_readMessage(&msg, 0, canSensor) == DW_SUCCESS)
    {
        // use received can message
    }
 
    // send message, e.g. asking for more data
    msg.id = 0xAAA;
    msg.data[0] = 0xFF;
    msg.size = 1;
    msg.timestamp = 0;
 
    // wait for 10ms at most if bus is busy
    dwSensorCAN_sendMessage(&msg, 10000, canSensor);
}
 
dwSensor_stop(canSensor);
dwSAL_releaseSensor(&canSensor);

For more information, refer to CAN Message Logger Sample.