DriveWorks SDK Reference
4.0.0 Release
For Test and Development only

Detailed Description

Defines the CAN sensor methods.

Data Structures

struct  dwCANMessage
 Holds a CAN package. More...
 

Modules

 Interpreter
 Defines the CAN message interpreter methods.
 
 Vehicle Data Interface
 Defines the methods used to obtain and store vehicle data.
 

Macros

#define DW_SENSORS_CAN_MAX_FILTERS   255
 Maximum number of filter that can be specified. More...
 
#define DW_SENSORS_CAN_MAX_ID_LEN   29
 This module provides access to the CAN bus typically used for communication between different ECUs in a vehicle. More...
 
#define DW_SENSORS_CAN_MAX_MESSAGE_LEN   64
 Maximal length of the supported CAN payload [bytes]. More...
 

Functions

DW_API_PUBLIC dwStatus dwSensorCAN_popMessage (dwCANMessage *msg, dwSensorHandle_t sensor)
 Returns any CAN data previously processed through a RAW data stream. More...
 
DW_API_PUBLIC dwStatus dwSensorCAN_processRawData (const uint8_t *data, size_t size, dwSensorHandle_t sensor)
 Decodes CAN data previously read as a RAW data stream into internal queue. More...
 
DW_API_PUBLIC dwStatus dwSensorCAN_readMessage (dwCANMessage *msg, dwTime_t timeout_us, dwSensorHandle_t sensor)
 Reads a CAN packet with a given timeout from the CAN bus. More...
 
DW_API_PUBLIC dwStatus dwSensorCAN_sendMessage (const dwCANMessage *msg, dwTime_t timeout_us, dwSensorHandle_t sensor)
 Sends a message over the CAN bus within a specified timeout. More...
 
DW_API_PUBLIC dwStatus dwSensorCAN_setMessageFilter (const uint32_t *ids, const uint32_t *masks, uint16_t num, dwSensorHandle_t sensor)
 Specifes a set of CAN IDs to be filtered. More...
 
DW_API_PUBLIC dwStatus dwSensorCAN_setUseHwTimestamps (bool flag, dwSensorHandle_t sensor)
 Enables or disables hardware timestamp of the CAN messages. More...
 

Data Structure Documentation

◆ dwCANMessage

struct dwCANMessage
Data Fields
uint8_t data[DW_SENSORS_CAN_MAX_MESSAGE_LEN] Payload.
uint32_t id CAN ID of the message sender.
uint16_t size Number of bytes of the payload.
dwTime_t timestamp_us Timestamp of the message in microseconds (using clock of the context).

Macro Definition Documentation

◆ DW_SENSORS_CAN_MAX_FILTERS

#define DW_SENSORS_CAN_MAX_FILTERS   255

Maximum number of filter that can be specified.

Definition at line 103 of file CAN.h.

◆ DW_SENSORS_CAN_MAX_ID_LEN

#define DW_SENSORS_CAN_MAX_ID_LEN   29

This module provides access to the CAN bus typically used for communication between different ECUs in a vehicle.

The implementation provides an abstracted layer over any implemented sensor drivers, supporting receive, send and filtering routines.

CAN data packet as of ISO 11898-1:

Byte:| 0 | 1 | 2 | 3 |
Bit: |07-06-05-04-03-02-01-00|15-14-13-12-11-10-09-08|23-22-21-20-19-18-17-16|31-30-29-28-27-26-25-24|
Byte:| 4 | 5 | 6 | 7 |
Bit: |39-38-37-36-35-34-33-32|47-46-45-44-43-42-41-40|55-54-53-52-51-50-49-48|63-62-61-60-59-58-57-56|
Note
Currently supported frame message format is ISO 11898-1.

Testing (Linux only)

If you have a real CAN device, activate it with this command:

:> sudo ip link set can0 up type can bitrate 500000

A virtual device is created using following commands:

:> sudo modprobe vcan
:> sudo ip link add dev vcan0 type vcan
:> sudo ip link set up vcan0

In order to send data from console to the virtual CAN bus, the cansend tool (from the can-utils package) can be used.

:> cansend vcan0 30B#1122334455667788

Maximal length of the supported CAN message id [bits].

Definition at line 97 of file CAN.h.

◆ DW_SENSORS_CAN_MAX_MESSAGE_LEN

#define DW_SENSORS_CAN_MAX_MESSAGE_LEN   64

Maximal length of the supported CAN payload [bytes].

Definition at line 100 of file CAN.h.

Function Documentation

◆ dwSensorCAN_popMessage()

DW_API_PUBLIC dwStatus dwSensorCAN_popMessage ( dwCANMessage msg,
dwSensorHandle_t  sensor 
)

Returns any CAN data previously processed through a RAW data stream.

This happens on the CPU thread where the function is called, incurring on additional load on that thread.

Parameters
[out]msgContainer for the decoded message.
[in]sensorSensor handle of the sensor previously created with 'dwSAL_createSensor()'.
Returns
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if given arguments are invalid.
DW_NOT_AVAILABLE - if no more data is available
DW_SUCCESS

◆ dwSensorCAN_processRawData()

DW_API_PUBLIC dwStatus dwSensorCAN_processRawData ( const uint8_t *  data,
size_t  size,
dwSensorHandle_t  sensor 
)

Decodes CAN data previously read as a RAW data stream into internal queue.

Any processed messages can be picked up using the dwSensorCAN_popMessage() method.

Parameters
[in]dataUndecoded CAN data.
[in]sizeSize in bytes of the raw data.
[in]sensorSensor handle of the sensor previously created with 'dwSAL_createSensor()'.
Returns
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if given arguments are invalid.
DW_FAILURE - if given raw stream data is not valid
DW_NOT_READY - if given raw stream did not have any data at all
DW_SUCCESS
See also
dwSensorCAN_popMessage()

◆ dwSensorCAN_readMessage()

DW_API_PUBLIC dwStatus dwSensorCAN_readMessage ( dwCANMessage msg,
dwTime_t  timeout_us,
dwSensorHandle_t  sensor 
)

Reads a CAN packet with a given timeout from the CAN bus.

The method blocks until either a new valid message is received on the bus or the given timeout exceeds.

Parameters
[out]msgA pointer to a CAN message structure to be filled with new data.
[in]timeout_usSpecifies a timeout, in us, to wait for a new message. Special values: DW_TIMEOUT_INFINITE - to wait infinitly. Zero - means polling of internal queue.
[in]sensorSpecifies a sensor handle of the CAN sensor previously created with 'dwSAL_createSensor()'.
Returns
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if given arguments are invalid.
DW_TIME_OUT - if operation has timeout.
DW_NOT_AVAILABLE - if sensor has not been started or data is not available in polling mode.
DW_SAL_SENSOR_ERROR - if there was an i/o or bus error.
DW_SUCCESS

◆ dwSensorCAN_sendMessage()

DW_API_PUBLIC dwStatus dwSensorCAN_sendMessage ( const dwCANMessage msg,
dwTime_t  timeout_us,
dwSensorHandle_t  sensor 
)

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

See also
dwSensorCAN_readMessage() operation has not yet finished.
Parameters
[in]msgA pointer to the message to be sent.
[in]timeout_usSpecifies the timeout, in microseconds, to wait at most before giving up.
[in]sensorSpecifies a CAN bus sensor to send the message over.
Returns
DW_NOT_SUPPORTED - if the underlying sensor does not support send operation.
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if given arguments are invalid.
DW_TIME_OUT - if operation has timed out.
DW_SAL_SENSOR_ERROR - if there was an i/o or bus error.
DW_NOT_AVAILABLE - if sensor has not been started.
DW_SUCCESS
Note
Send operation using can.virtual is a no-op and returns always DW_SUCCESS

◆ dwSensorCAN_setMessageFilter()

DW_API_PUBLIC dwStatus dwSensorCAN_setMessageFilter ( const uint32_t *  ids,
const uint32_t *  masks,
uint16_t  num,
dwSensorHandle_t  sensor 
)

Specifes a set of CAN IDs to be filtered.

The filter is active if it contains at least one sender ID.

Parameters
[in]idsA pointer to an array of CAN IDs to be filtered. Any matching CAN ID is used together with the mask to filter.
[in]masksA pointer to an array of filter masks to be applied. A mask is applied together with the ID as 'id & mask'. If mask is set to NULL, a default mask of '1FFFFFFF' is used.
[in]numSpecifies the number of elements passed in the array. To remove the filter, pass 0.
[in]sensorSpecifies the sensor handle of the CAN sensor previously created with 'dwSAL_createSensor()'.
Returns
DW_NOT_SUPPORTED - if the underlying sensor does not support filter operation.
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if given arguments are invalid.
DW_SAL_SENSOR_ERROR - if there was a sensor error, i.e., filter cannot be set.
DW_SUCCESS
Note
Some CAN implementations, such as AurixCAN, only support a few messages for a filter.
The effect takes place on the next (re)start of the sensor.
The general implementation is to pass a message if 'received_can_id & mask == can_id & mask'. If multiple filters are provided, a message is passed if at least one of the filters match.

◆ dwSensorCAN_setUseHwTimestamps()

DW_API_PUBLIC dwStatus dwSensorCAN_setUseHwTimestamps ( bool  flag,
dwSensorHandle_t  sensor 
)

Enables or disables hardware timestamp of the CAN messages.

Hardware timestamps are used per default when supported by the sensor. If HW timestamps are not supported, SW timestamps are used per default. HW timestamps can be turned off if the default behavior is not working properly with the current hardware stack.

Note
The effect takes place on the next (re)start of the sensor.
Parameters
[in]flagSpecifies either 'true' or 'false' to enable or disable hardware timestamping.
[in]sensorSpecifies the sensor handle of the CAN sensor previously created with 'dwSAL_createSensor()'.
Attention
If the same physical CAN device/interface is shared by multiple sensors, setting HW timestamping affects timestamping of all sensors sharing the same device.
Note
If using AurixCAN as a driver, hardware timestamps are used as timestamped by Aurix.
Returns
DW_NOT_SUPPORTED - if the underlying sensor does not support hardware timestamps.
DW_INVALID_HANDLE - if given sensor handle is invalid
DW_INVALID_ARGUMENT - if given arguments are invalid
DW_SUCCESS