DriveWorks SDK Reference
3.0.4260 Release
For Test and Development only

Detailed Description

Defines the CAN message interpreter methods.

Note
SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures

struct  dwCANInterpreterInterface
 Interface for callback based CAN data interpreter. More...
 

Macros

#define DW_SENSORS_CAN_INTERPRETER_MAX_MESSAGE_NAME_LEN   32
 Maximal length of a message name [characters]. More...
 
#define DW_SENSORS_CAN_INTERPRETER_MAX_SIGNAL_NAME_LEN   32
 Maximal length of a signal name [characters]. More...
 
#define DW_SENSORS_CAN_INTERPRETER_MESSAGE_MAX_SIGNALS   128
 Maximal number of signals in a DBC message. More...
 

Typedefs

typedef void(* dwCANInterpreterAddMessageFunc_t) (const dwCANMessage *msg, void *userData)
 Pushes new messages to the interpreter. More...
 
typedef bool(* dwCANInterpreterGetDataf32Func_t) (float32_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)
 Returns false if no float32 data is available. More...
 
typedef bool(* dwCANInterpreterGetDataf64Func_t) (float64_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)
 Returns false if no float64 data is available. More...
 
typedef bool(* dwCANInterpreterGetDatai32Func_t) (int32_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)
 Returns false if no int32 data is available. More...
 
typedef uint32_t(* dwCANInterpreterGetNumAvailableFunc_t) (void *userData)
 Gets the number of signals available to be retrieved. The same signal may be available multiple times. More...
 
typedef bool(* dwCANInterpreterGetSignalInfoFunc_t) (const char **name, dwTrivialDataType *type, dwCANVehicleData *data, uint32_t idx, void *userData)
 Gets the name and type of a signal; the callback must return false if the query fails. More...
 
typedef struct dwCANInterpreterObject * dwCANInterpreterHandle_t
 CAN message interpreter handle. More...
 

Functions

DW_API_PUBLIC dwStatus dwCANInterpreter_buildFromCallbacks (dwCANInterpreterHandle_t *interpreter, dwCANInterpreterInterface callbacks, void *userData, dwContextHandle_t context)
 Creates a CAN data interpreter based on user provided callbacks. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_buildFromDBC (dwCANInterpreterHandle_t *interpreter, const char *inputDBC, dwContextHandle_t ctx)
 Creates a CAN data interpreter based on DBC file format. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_consume (const dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Pushes a new message to the interpreter. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_createMessage (dwCANMessage *msg, uint32_t id, dwCANInterpreterHandle_t interpreter)
 Initializes an empty can message an interpreter can encoded signals into. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_createMessageFromName (dwCANMessage *msg, const char *msgName, dwCANInterpreterHandle_t interpreter)
 Initializes an empty can message an interpreter can encoded signals into. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_encodef32 (float32_t value, const char *signal, dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Encodes a value for a signal into a given message. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_encodef64 (float64_t value, const char *signal, dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Same as dwCANInterpreter_encodef32, but for float64 types. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_encodei32 (int32_t value, const char *signal, dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Same as dwCANInterpreter_encodef32, but for int32 types. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getDataSignalIndex (uint32_t *idx, dwCANVehicleData data, dwCANInterpreterHandle_t interpreter)
 Gets the index of a signal of the last consumed message that corresponds to a certain predefined data type. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getf32 (float32_t *value, dwTime_t *timestamp_us, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Gets a 'float32_t' value from the available values. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getf64 (float64_t *value, dwTime_t *timestamp_us, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Same as dwCANInterpreter_getf32, but for float64 types. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_geti32 (int32_t *value, dwTime_t *timestamp_us, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Same as dwCANInterpreter_getf32, but for int32 types. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getNumberSignals (uint32_t *num, dwCANInterpreterHandle_t interpreter)
 Gets the number of signals decoded and available for consumption by the application side. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getNumberSignalsInMessage (uint32_t *num, const dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Gets the number of signals a CAN interpreter can encode into the provided message. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalName (const char **name, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Gets the name of a signal available for consumption by the application as a string. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalNameInMessage (const char **name, uint32_t idx, const dwCANMessage *msg, dwCANInterpreterHandle_t interpreter)
 Gets the name of a signal that the CAN interpreter can encode in the currently active encoded message. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalRange (float64_t *minimum, float64_t *maximum, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Returns the range of validity of data for a signal available for consumption by the application. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalType (dwTrivialDataType *type, uint32_t idx, dwCANInterpreterHandle_t interpreter)
 Returns the type of the value of a signal available for consumption by the application. More...
 
DW_API_PUBLIC dwStatus dwCANInterpreter_release (dwCANInterpreterHandle_t interpreter)
 Closes previously opened interpreter. More...
 

Data Structure Documentation

◆ dwCANInterpreterInterface

Macro Definition Documentation

◆ DW_SENSORS_CAN_INTERPRETER_MAX_MESSAGE_NAME_LEN

#define DW_SENSORS_CAN_INTERPRETER_MAX_MESSAGE_NAME_LEN   32

Maximal length of a message name [characters].

Definition at line 61 of file Interpreter.h.

◆ DW_SENSORS_CAN_INTERPRETER_MAX_SIGNAL_NAME_LEN

#define DW_SENSORS_CAN_INTERPRETER_MAX_SIGNAL_NAME_LEN   32

Maximal length of a signal name [characters].

Definition at line 64 of file Interpreter.h.

◆ DW_SENSORS_CAN_INTERPRETER_MESSAGE_MAX_SIGNALS

#define DW_SENSORS_CAN_INTERPRETER_MESSAGE_MAX_SIGNALS   128

Maximal number of signals in a DBC message.

Definition at line 58 of file Interpreter.h.

Typedef Documentation

◆ dwCANInterpreterAddMessageFunc_t

typedef void(* dwCANInterpreterAddMessageFunc_t) (const dwCANMessage *msg, void *userData)

Pushes new messages to the interpreter.

Definition at line 74 of file Interpreter.h.

◆ dwCANInterpreterGetDataf32Func_t

typedef bool(* dwCANInterpreterGetDataf32Func_t) (float32_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)

Returns false if no float32 data is available.

Definition at line 85 of file Interpreter.h.

◆ dwCANInterpreterGetDataf64Func_t

typedef bool(* dwCANInterpreterGetDataf64Func_t) (float64_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)

Returns false if no float64 data is available.

Definition at line 88 of file Interpreter.h.

◆ dwCANInterpreterGetDatai32Func_t

typedef bool(* dwCANInterpreterGetDatai32Func_t) (int32_t *value, dwTime_t *timestamp_us, uint32_t idx, void *userData)

Returns false if no int32 data is available.

Definition at line 91 of file Interpreter.h.

◆ dwCANInterpreterGetNumAvailableFunc_t

typedef uint32_t(* dwCANInterpreterGetNumAvailableFunc_t) (void *userData)

Gets the number of signals available to be retrieved. The same signal may be available multiple times.

Definition at line 77 of file Interpreter.h.

◆ dwCANInterpreterGetSignalInfoFunc_t

typedef bool(* dwCANInterpreterGetSignalInfoFunc_t) (const char **name, dwTrivialDataType *type, dwCANVehicleData *data, uint32_t idx, void *userData)

Gets the name and type of a signal; the callback must return false if the query fails.

Definition at line 80 of file Interpreter.h.

◆ dwCANInterpreterHandle_t

typedef struct dwCANInterpreterObject* dwCANInterpreterHandle_t

CAN message interpreter handle.

Definition at line 71 of file Interpreter.h.

Function Documentation

◆ dwCANInterpreter_buildFromCallbacks()

DW_API_PUBLIC dwStatus dwCANInterpreter_buildFromCallbacks ( dwCANInterpreterHandle_t interpreter,
dwCANInterpreterInterface  callbacks,
void *  userData,
dwContextHandle_t  context 
)

Creates a CAN data interpreter based on user provided callbacks.

Such an interpreter can be used same way as the DBC based one. Any non-provided method, i.e., set to NULL, is indicated with DW_NOT_IMPLEMENTED error when calling the corresponding interpreter method.

Note
this interpreter does not support the creation of messages and encoding of data.
Parameters
[out]interpreterA pointer to the place to return a valid interpreter handle on success.
[in]callbacksSpecifies a set of callback defining the interpreter interface.
[in]userDataA pointer to the user data to be passed to callbacks.
[in]contextSpecifies the handler to the context under which the interpreted is to be created.
Returns
DW_INVALID_ARGUMENT if all 'addMessage', 'getNumAvailableSignals' or 'getSignalInfo' methods are NULL
DW_INVALID_HANDLE if provided context is invalid
DW_SUCCESS

◆ dwCANInterpreter_buildFromDBC()

DW_API_PUBLIC dwStatus dwCANInterpreter_buildFromDBC ( dwCANInterpreterHandle_t interpreter,
const char *  inputDBC,
dwContextHandle_t  ctx 
)

Creates a CAN data interpreter based on DBC file format.

Note
For generating the interpreter from DBC file format, a parser:
  1. prints out the summary of parsing in debug logger.
  2. supports only Simple Signal Multiplexing (8-bit mux) (does not support Extended Signal Multiplexing).
  3. supports up to DW_SENSORS_CAN_INTERPRETER_MESSAGE_MAX_SIGNALS signals in a message.
  4. supports extended CAN format.
  5. ignores messages with no signals defined.
  6. ignores messages defined with data length as 0 bytes.
  7. ignores Signal Type and Signal Group Definitions (normally not used).
  8. does not support signal sizes larger than 32 bits.
Parameters
[out]interpreterA pointer to the place to return a valid interpreter handle on success.
[in]inputDBCA pointer to the file path for the input DBC file.
[in]ctxSpecifies the handler to the context under which the interpreter is to be created.
Returns
DW_INVALID_ARGUMENT if some inputs are NULL.
DW_INVALID_HANDLE if provided context is invalid.
DW_SUCCESS if successfully completed.

◆ dwCANInterpreter_consume()

DW_API_PUBLIC dwStatus dwCANInterpreter_consume ( const dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Pushes a new message to the interpreter.

It is the responsibility of the interpreter to parse the message and fill out internal structures to be capable of delivering the current vehicle state to the application. The state can be retrieved using the 'dwCANInterpreter_getX()' methods.

Parameters
[in]msgA pointer to the CAN frame to be consumed by the interpreter.
[in]interpreterSpecifies the interpreter handle previously created or opened through a file.
Returns
DW_INVALID_HANDLE if provided interpreter handle is invalid.
DW_NOT_IMPLEMENTED if provided interpreter does not implement the necessary callbacks.
DW_SUCCESS

◆ dwCANInterpreter_createMessage()

DW_API_PUBLIC dwStatus dwCANInterpreter_createMessage ( dwCANMessage msg,
uint32_t  id,
dwCANInterpreterHandle_t  interpreter 
)

Initializes an empty can message an interpreter can encoded signals into.

Note
This API is currently only supported by the interpreter built from DBC file.
Parameters
[out]msgA pointer to a CAN message to be initialized.
[in]idCAN ID of the message.
[in]interpreterSpecifies the interpreter handle previously create or opened through a file.
Returns
DW_INVALID_ARGUMENT if the given pointer is NULL or the message id is unknown to the interpreter.
DW_NOT_SUPPORTED if provided interpreter does not support this method.
DW_SUCCESS

◆ dwCANInterpreter_createMessageFromName()

DW_API_PUBLIC dwStatus dwCANInterpreter_createMessageFromName ( dwCANMessage msg,
const char *  msgName,
dwCANInterpreterHandle_t  interpreter 
)

Initializes an empty can message an interpreter can encoded signals into.

Note
This API is currently only supported by the interpreter built from DBC file.
Parameters
[out]msgA pointer to a CAN message to be initialized.
[in]msgNameName of the CAN message.
[in]interpreterSpecifies the interpreter handle previously create or opened through a file.
Returns
DW_INVALID_ARGUMENT if the given pointer is NULL or the message id is unknown to the interpreter.
DW_NOT_SUPPORTED if provided interpreter does not support this method.
DW_SUCCESS

◆ dwCANInterpreter_encodef32()

DW_API_PUBLIC dwStatus dwCANInterpreter_encodef32 ( float32_t  value,
const char *  signal,
dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Encodes a value for a signal into a given message.

The signal must be defined within the message ID. The size of the message changes to be at least the size required to cover the encoded value.

Note
This API is currently only supported by an interpreter built from DBC file.
Parameters
[in]valueThe value for the signal to be encoded.
[in]signalSpecifies the name of the signal to set value.
[in]msgCAN message to be used for encoding.
[in]interpreterSpecifies the interpreter handle previously created.
Returns
DW_INVALID_ARGUMENT if given pointer is NULL.
DW_NOT_AVAILABLE if given signal name is not available in this message.
DW_NOT_SUPPORTED if provided interpreter does not support this method.
DW_SUCCESS
Note
Given CAN message must have a valid id set. The signal must be available in the given message.

◆ dwCANInterpreter_encodef64()

DW_API_PUBLIC dwStatus dwCANInterpreter_encodef64 ( float64_t  value,
const char *  signal,
dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Same as dwCANInterpreter_encodef32, but for float64 types.

See also
dwCANInterpreter_encodef32

◆ dwCANInterpreter_encodei32()

DW_API_PUBLIC dwStatus dwCANInterpreter_encodei32 ( int32_t  value,
const char *  signal,
dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Same as dwCANInterpreter_encodef32, but for int32 types.

See also
dwCANInterpreter_encodef32

◆ dwCANInterpreter_getDataSignalIndex()

DW_API_PUBLIC dwStatus dwCANInterpreter_getDataSignalIndex ( uint32_t *  idx,
dwCANVehicleData  data,
dwCANInterpreterHandle_t  interpreter 
)

Gets the index of a signal of the last consumed message that corresponds to a certain predefined data type.

Some SDK modules need to know how to access data from CAN bus, independent on the definition of the signal name.

Note
This API is not supported by an interpreter built from DBC file.
Parameters
[out]idxAn index is returned here. On succes the index is in range [0; dwCANInterpreter_getNumberSignals()-1].
[in]dataSpecifies the ID of the data signal you are interested in.
[in]interpreterSpecifies the interpreter handle previously created.
Returns
DW_SUCCESS if data signal is ready to be gathered.
DW_NOT_AVAILABLE if the last consumed message does not provide a signal for the requested data signal.
DW_INVALID_HANDLE if given handle is invalid.
DW_INVALID_ARGUMENT if given arguments are invalid, i.e., NULL.
DW_NOT_IMPLEMENTED if provided interpreter does not support querying.

◆ dwCANInterpreter_getf32()

DW_API_PUBLIC dwStatus dwCANInterpreter_getf32 ( float32_t value,
dwTime_t timestamp_us,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Gets a 'float32_t' value from the available values.

The timestamp represent the time when the signal value was valid, i.e., when signal was received.

Note
Each signal value can only be obtained once per consumed message.
In case of DBC based interpreter, if both maximum and minimum are zero for a given signal in DBC, the range restriction is invalidated.
Parameters
[out]valueA pointer to the data value is returned here.
[out]timestamp_usTimestamp of the signal.
[in]idxSpecifies the index within the max event numbers from dwCANInterpreter_getNumberSignals API.
[in]interpreterA pointer to the interpreter handle previously created or opened through a file.
Returns
DW_INVALID_HANDLE if given interpreter handle is not valid.
DW_INVALID_ARGUMENT if given pointers are invalid.
DW_NOT_AVAILABLE if no data update happened, i.e., no data was retrieved.
DW_SUCCESS

◆ dwCANInterpreter_getf64()

DW_API_PUBLIC dwStatus dwCANInterpreter_getf64 ( float64_t value,
dwTime_t timestamp_us,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Same as dwCANInterpreter_getf32, but for float64 types.

See also
dwCANInterpreter_getf32

◆ dwCANInterpreter_geti32()

DW_API_PUBLIC dwStatus dwCANInterpreter_geti32 ( int32_t *  value,
dwTime_t timestamp_us,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Same as dwCANInterpreter_getf32, but for int32 types.

See also
dwCANInterpreter_getf32

◆ dwCANInterpreter_getNumberSignals()

DW_API_PUBLIC dwStatus dwCANInterpreter_getNumberSignals ( uint32_t *  num,
dwCANInterpreterHandle_t  interpreter 
)

Gets the number of signals decoded and available for consumption by the application side.

In general the number of signals is the number of valid signals found in last consumed CAN message. However this does not have to be true in all cases, especially in callback based interpreters.

Parameters
[out]numA pointer to the variable to be filled with the number.
[in]interpreterSpecifies the interpreter handle previously created or opened through a file.
Returns
DW_INVALID_HANDLE if provided interpreter handle is invalid.
DW_INVALID_ARGUMENT if given pointer is NULL.
DW_SUCCESS

◆ dwCANInterpreter_getNumberSignalsInMessage()

DW_API_PUBLIC dwStatus dwCANInterpreter_getNumberSignalsInMessage ( uint32_t *  num,
const dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Gets the number of signals a CAN interpreter can encode into the provided message.

Note
This API is currently only supported by the interpreter built from DBC file.
Parameters
[out]numA pointer to variable, which is filled with the number.
[in]msgCAN message to be used for encoding.
[in]interpreterSpecifies the interpreter handle previously create or opened through a file.
Returns
DW_INVALID_ARGUMENT if the given pointer is NULL.
DW_NOT_SUPPORTED if the provided interpreter does not support this method.
DW_SUCCESS
Note
A valid CAN message id must be set in the provided message.

◆ dwCANInterpreter_getSignalName()

DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalName ( const char **  name,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Gets the name of a signal available for consumption by the application as a string.

Parameters
[out]nameA pointer to a const char array containing a null-terminated string with signal name.
[in]idxSpecifies the index of a signal that is in range [0; dwCANInterpreter_getNumberSignals()-1].
[in]interpreterSpecifies the interpreter handle previously created or opened through a file.
Returns
DW_INVALID_HANDLE if provided interpreter handle is invalid.
DW_INVALID_ARGUMENT if given index or pointer are invalid.
DW_SUCCESS

◆ dwCANInterpreter_getSignalNameInMessage()

DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalNameInMessage ( const char **  name,
uint32_t  idx,
const dwCANMessage msg,
dwCANInterpreterHandle_t  interpreter 
)

Gets the name of a signal that the CAN interpreter can encode in the currently active encoded message.

Note
This API is currently only supported by an interpreter built from DBC file.
Parameters
[out]nameA pointer to a const char array containing a null-terminated string with signal name.
[in]idxSpecifies the index of a signal that is in range [0:dwCANInterpreter_getNumberSignalsInMessage()-1].
[in]msgCAN message to be used for encoding.
[in]interpreterSpecifies the interpreter handle previously created or opened through a file.
Returns
DW_INVALID_ARGUMENT if given pointer is NULL or the index is out of range
DW_NOT_AVAILABLE if no encoding has been started
DW_NOT_SUPPORTED if provided interpreter does not support this method.
DW_SUCCESS

◆ dwCANInterpreter_getSignalRange()

DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalRange ( float64_t minimum,
float64_t maximum,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Returns the range of validity of data for a signal available for consumption by the application.

Parameters
[out]minimumThe minimum of the range of validity.
[out]maximumThe maximum of the range of validity.
[in]idxSpecifies the index of a signal that is in range [0; dwCANInterpreter_getNumberSignals()-1].
[in]interpreterSpecifies the interpreter handle previously created.
Returns
DW_INVALID_HANDLE if provided interpreter handle is invalid.
DW_INVALID_ARGUMENT if given index or pointer are invalid.
DW_SUCCESS

◆ dwCANInterpreter_getSignalType()

DW_API_PUBLIC dwStatus dwCANInterpreter_getSignalType ( dwTrivialDataType type,
uint32_t  idx,
dwCANInterpreterHandle_t  interpreter 
)

Returns the type of the value of a signal available for consumption by the application.

Parameters
[out]typeThe data type is returned here.
[in]idxSpecifies the index of a signal that is in range [0; dwCANInterpreter_getNumberSignals()-1].
[in]interpreterSpecifies the interpreter handle previously created.
Returns
DW_SUCCESS if signal is supported.
DW_INVALID_HANDLE if given handle is invalid.
DW_INVALID_ARGUMENT if given arguments are invalid, i.e., NULL.
DW_FAILURE on any other error.

◆ dwCANInterpreter_release()

DW_API_PUBLIC dwStatus dwCANInterpreter_release ( dwCANInterpreterHandle_t  interpreter)

Closes previously opened interpreter.

This unloads the interpreter plugin as well as deallocates previously allocated memory.

Note
The given interpreter handle is set to NULL on success.
Parameters
[in]interpreterThe interpreter handle previously created or opened through a file.
Returns
DW_INVALID_HANDLE if provided interpreter handle is invalid.
DW_SUCCESS