DriveWorks SDK Reference
4.0.0 Release
For Test and Development only

src/dw/sensors/canbus/docs/usecase3.md
Go to the documentation of this file.
1 # Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved.
2 
3 @page canbus_usecase3 CAN Interpreter
4 
5 ## CAN Interpreter Module workflow
6 
7 ### Initialization
8 
9 The interpreter module for DBC format is initialized as follows:
10 
11 ```{.cpp}
12 dwCANInterpreterHandle_t interpreter;
13 dwCANInterpreter_buildFromDBC(&interpreter, "path/to/definition.dbc", ...);
14 ```
15 
16 The DBC message and signals definition file will be parsed to initialize
17 the interpreter. Please refer to a DBC file format documentation for additional
18 details on the expected syntax.
19 
20 An interpreter for user-defined format is initialized as follows:
21 
22 ```{.cpp}
23 dwCANInterpreterInterface interpreter;
24 
25 // following callbacks to be implemented by user
26 interpreter.addMessage = cb_addMessage;
27 interpreter.getDataf32 = cb_getDataf32;
28 interpreter.getDataf64 = cb_getDataf64;
29 interpreter.getDatai32 = cb_getDatai32;
30 interpreter.getNumAvailableSignals = cb_getNumAvailableSignals;
31 interpreter.getSignalInfo = cb_getSignalInfo;
32 
33 dwCANInterpreter_buildFromCallbacks(&canParser, interpreter, NULL, ...);
34 ```
35 
36 The `dwCANInterpreterInterface` structure is populated with pointers
37 to the callbacks implemented by the user. The expected callback signatures are
38 detailed in Interpreter.h. The callbacks are used as follows:
39 
40 - `dwCANInterpreterInterface.addMessage` gets called with a `dwCANMessage` to be interpreted
41 - `dwCANInterpreterInterface.getNumAvailableSignals` and `dwCANInterpreterInterface.getSignalInfo` are used to extract signals from CAN messages
42 - `dwCANInterpreterInterface.getDataf32`, `dwCANInterpreterInterface.getDataf64` and `dwCANInterpreterInterface.getDatai32` are used to read the corresponding signal type data from each message
43 
44 The following callbacks are required to be implemented:
45 
46 - `addMessage`
47 - `getNumAvailableSignals`
48 - `getSignalInfo`
49 
50 The following callbacks are optional and have to be implemented only
51 if a signal data type requires them:
52 
53 - `getDataf32`
54 - `getDataf64`
55 - `getDatai32`
56 
57 An example implementation of those callbacks is provided in @ref dwx_canbus_message_sample
58 
59 ### Consuming messages
60 
61 CAN messages can be provided to the interpreter for parsing as follows:
62 
63 ```{.cpp}
64 dwCANInterpreter_consume(&msg, interpreter);
65 ```
66 
67 Then used as follows:
68 
69 ```{.cpp}
70 uint32_t num;
71 dwStatus status = dwCANInterpreter_getNumberSignals(&num, interpreter);
72 
73 if (status == DW_SUCCESS && num > 0)
74 {
75  int32_t int_value = 0;
76  float32_t float_value = 0;
77  dwTime_t timestamp = 0;
78  const char* name;
79 
80  // for each signal
81  for (uint32_t i = 0; i < num; ++i)
82  {
83  // get name of signal
84  if (dwCANInterpreter_getSignalName(&name, i, interpreter) == DW_SUCCESS)
85  {
86  // do something based on signal name
87  if (strcmp(name, "some_signal_int") == 0)
88  {
89  if (dwCANInterpreter_geti32(&int_value, &timestamp, i, interpreter) == DW_SUCCESS)
90  std::cout << "some_signal_int value: " << int_value << std::endl;
91  else
92  std::cerr << "error getting value for some_signal_int" << std::endl;
93  }
94  elseif (strcmp(name, "some_signal_float") == 0)
95  {
96  if (dwCANInterpreter_getf32(&float_value, &timestamp, i, interpreter) == DW_SUCCESS)
97  std::cout << "some_signal_float value: " << float_value << std::endl;
98  else
99  std::cerr << "error getting value for some_signal_float" << std::endl;
100  }
101  else std::cerr << "unhandled signal name" << std::endl;
102  }
103  }
104 }
105 ```
106 
107 The above snippet iterates over all signals handled by the intepreter, and
108 attempts to read a value for each signal, in the latest consumed `dwCANMessage`.
109 
110 Note that in general the number of signals as returned by
111 `dwCANInterpreter_getNumberSignals()` is the number of valid signals found
112 in last consumed CAN message. However this does not have to be true in
113 user-provided callback based interpreters, as it is implementation dependent.
114 
115 ### Releasing the interpreter
116 
117 The interpreter can be released as follows:
118 
119 ```{.cpp}
120 dwCANInterpreter_release(&interpreter);
121 ```
122 
123 For more details see @ref dwx_canbus_message_sample