CAN Sensor

Detailed Description

Defines the CAN sensor methods.

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

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 *const msg, dwTime_t const timeoutUs, dwSensorHandle_t const sensor)
	Reads a CAN packet (raw data and process it) within a given timeout from the CAN bus. More...
DW_API_PUBLIC dwStatus	dwSensorCAN_sendMessage (const dwCANMessage *const msg, dwTime_t const timeoutUs, dwSensorHandle_t const 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 const flag, dwSensorHandle_t const sensor)
	Enables or disables hardware timestamp of the CAN messages. More...
#define	DW_SENSORS_CAN_MAX_ID_LEN   29
	Defines the CAN sensor types. More...
#define	DW_SENSORS_CAN_MAX_MESSAGE_LEN   64
	Maximal length of the supported CAN payload [bytes]. More...
#define	DW_SENSORS_CAN_MAX_FILTERS   255
	Maximum number of filter that can be specified. More...

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 98 of file CANTypes.h.

DW_SENSORS_CAN_MAX_ID_LEN

#define DW_SENSORS_CAN_MAX_ID_LEN   29

Defines the CAN sensor types.

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 92 of file CANTypes.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 95 of file CANTypes.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]	msg	Container for the decoded message.
[in]	sensor	Sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if msg pointer is null.
DW_NOT_AVAILABLE - if no more data is available
DW_SUCCESS - if operation succeeds.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

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.

Parameters

[in]	data	Undecoded CAN data.
[in]	size	Size in bytes of the raw data.
[in]	sensor	Sensor handle of the sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if data pointer is null.
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 - if operation succeeds.

See also

dwSensorCAN_popMessage()

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwSensorCAN_readMessage()

DW_API_PUBLIC dwStatus dwSensorCAN_readMessage	(	dwCANMessage *const	msg,
		dwTime_t const	timeoutUs,
		dwSensorHandle_t const	sensor
	)

Reads a CAN packet (raw data and process it) within 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]	msg	A pointer to a CAN message structure to be filled with new data.
[in]	timeoutUs	Specifies 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]	sensor	Specifies a sensor handle of the CAN sensor previously created with 'dwSAL_createSensor()'.

Returns

DW_SUCCESS - A new message has been successfully read
DW_INVALID_HANDLE - if given sensor handle is invalid.
DW_INVALID_ARGUMENT - if msg pointer is null.
DW_TIME_OUT - If a timeout occurred during read of a new raw CAN packet from the CAN bus
DW_END_OF_STREAM - End of raw data stream reached
DW_FILE_INVALID - Raw data stream content is invalid
DW_SAL_SENSOR_ERROR - I/O bus error
DW_NOT_AVAILABLE - if the sensor has not been initialized and started.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwSensorCAN_sendMessage()

DW_API_PUBLIC dwStatus dwSensorCAN_sendMessage	(	const dwCANMessage *const	msg,
		dwTime_t const	timeoutUs,
		dwSensorHandle_t const	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 dwSensorCAN_readMessage() operation has not yet finished. The way the message is packed and sent to the sensor depends on the specific CAN class implementation used.

Parameters

[in]	msg	A pointer to the message to be sent.
[in]	timeoutUs	Specifies the timeout, in microseconds from system epoch, to wait at most before giving up.
[in]	sensor	Specifies a CAN bus sensor to send the message over.

Returns

DW_SUCCESS - The message has been sent successfully on the CAN bus
DW_NOT_IMPLEMENTED - if the concrecte CAN class used does not implement the send operation
DW_INVALID_HANDLE - if given sensor handle is invalid
DW_INVALID_ARGUMENT - if msg pointer is null
DW_TIME_OUT - If a timeout occurred while sending the message
DW_SAL_SENSOR_ERROR - I/O bus error
DW_NOT_AVAILABLE - if the sensor has not been initialized and started

Note

Send operation using can.virtual is a no-op and returns always DW_SUCCESS

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

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]	ids	A pointer to an array of CAN IDs to be filtered. Any matching CAN ID is used together with the mask to filter.
[in]	masks	A 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]	num	Specifies the number of elements passed in the array. To remove the filter, pass 0.
[in]	sensor	Specifies 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 ids or masks pointers are null.
DW_SAL_SENSOR_ERROR - if there was a sensor error, i.e., filter cannot be set.
DW_SUCCESS - if operation succeeds.

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.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwSensorCAN_setUseHwTimestamps()

DW_API_PUBLIC dwStatus dwSensorCAN_setUseHwTimestamps	(	bool const	flag,
		dwSensorHandle_t const	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 and no operation shall be performed. HW timestamps can be turned off if the default behavior is not working properly with the current hardware stack. If any result different from DW_SUCCESS is returned, no operation shall be performed by this method.

Note

The effect takes place on the next (re)start of the sensor.

Parameters

[in]	flag	Specifies either 'true' or 'false' to enable or disable hardware timestamping.
[in]	sensor	Specifies 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_SUCCESS - if operation succeeds.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes