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 *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...

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 from system epoch (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]	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.

◆ 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()

◆ 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.

◆ 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

◆ 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.

◆ 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.

Detailed Description

Data Structures

Modules

Macros

Functions

Data Structure Documentation

◆ dwCANMessage

Macro Definition Documentation

◆ DW_SENSORS_CAN_MAX_FILTERS

◆ DW_SENSORS_CAN_MAX_ID_LEN

Testing (Linux only)

◆ DW_SENSORS_CAN_MAX_MESSAGE_LEN

Function Documentation

◆ dwSensorCAN_popMessage()

◆ dwSensorCAN_processRawData()

◆ dwSensorCAN_readMessage()

◆ dwSensorCAN_sendMessage()

◆ dwSensorCAN_setMessageFilter()

◆ dwSensorCAN_setUseHwTimestamps()