1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
Unified Diagnostic Services (UDS) Support Library in C
======================================================
This is a platform agnostic C library that implements the Unified Diagnostics
Services protocol for automotive electronics. UDS is documented in ISO 14229 and
is the underpinning for the more well-known On-board Diagnostics (OBD) standard.
The library currently supports UDS running over CAN (ISO 15765-4), which uses
the ISO-TP (ISO 15765-2) protocol for message framing.
This library doesn't assume anything about the source of your diagnostic message
requests or underlying interface to the CAN bus. It uses dependency injection to
give you complete control.
## Usage
First, create some shim functions to let this library use your lower level
system:
// required, this must send a single CAN message with the given arbitration
// ID (i.e. the CAN message ID) and data. The size will never be more than 8
// bytes.
bool send_can(const uint16_t arbitration_id, const uint8_t* data,
const uint8_t size) {
...
}
// optional, provide to receive debugging log messages
void debug(const char* format, ...) {
...
}
// not used in the current version
void set_timer(uint16_t time_ms, void (*callback)) {
...
}
With your shims in place, create a `DiagnosticShims` object to pass them around:
DiagnosticShims shims = diagnostic_init_shims(debug, send_can, set_timer);
With your shims in hand, send a simple PID request to the standard broadcast
address, `0x7df` (we use the constant `OBD2_FUNCTIONAL_BROADCAST_ID` here):
// Optional: This is your callback that will be called the response to your
// diagnostic request is received.
void response_received_handler(const DiagnosticResponse* response) {
// You received a response! Do something with it.
}
DiagnosticRequestHandle handle = diagnostic_request_pid(&shims,
DIAGNOSTIC_STANDARD_PID, // this is a standard PID request, not an extended or enhanced one
OBD2_FUNCTIONAL_BROADCAST_ID, // the request is going out to the broadcast arbitration ID
0x2, // we want PID 0x2
response_received_handler); // our callback (optional, use NULL if you don't have one)
if(handle.completed) {
if(!handle.success) {
// something happened and it already failed - possibly we aren't
// able to send CAN messages
return;
} else {
// this should never occur right away - you need to receive a fresh
// CAN message first
}
} else {
while(true) {
// Continue to read from CAN, passing off each message to the handle.
// This will return a 'completed' DiagnosticResponse when the when
// the request is completely sent and the response is received
// (which may take more than 1 CAN frames)
DiagnosticResponse response = diagnostic_receive_can_frame(&shims,
&handle, can_message_id, can_data, sizeof(can_data));
if(response.completed && handle.completed) {
if(handle.success) {
if(response.success) {
// The request was sent successfully, the response was
// received successfully, and it was a positive response - we
// got back some data!
} else {
// The request was sent successfully, the response was
// received successfully, BUT it was a negative response
// from the other node.
printf("This is the error code: %d", response.negative_response_code);
}
} else {
// Some other fatal error ocurred - we weren't able to send
// the request or receive the response. The CAN connection
// may be down.
}
}
}
}
### Requests for other modes
If you want to do more besides PID requests on mode 0x1 and 0x22, there's a
lower level API you can use. Here's how to make a mode 3 request to get DTCs.
DiagnosticRequest request = {
arbitration_id: OBD2_FUNCTIONAL_BROADCAST_ID,
mode: OBD2_MODE_EMISSIONS_DTC_REQUEST
};
DiagnosticRequestHandle handle = diagnostic_request(&SHIMS, &request, NULL);
if(handle.completed) {
if(!handle.success) {
// something happened and it already failed - possibly we aren't
// able to send CAN messages
return;
} else {
// this should never occur right away - you need to receive a fresh
// CAN message first
}
} else {
while(true) {
// Continue to read from CAN, passing off each message to the handle.
// This will return a 'completed' DiagnosticResponse when the when
// the request is completely sent and the response is received
// (which may take more than 1 CAN frames)
DiagnosticResponse response = diagnostic_receive_can_frame(&shims,
&handle, can_message_id, can_data, sizeof(can_data));
if(response.completed && handle.completed) {
if(handle.success) {
if(response.success) {
// The request was sent successfully, the response was
// received successfully, and it was a positive response - we
// got back some data!
printf("The DTCs are: ");
for(int i = 0; i < response.payload_length; i++) {
printf("0x%x ", response.payload[i]);
}
} else {
// The request was sent successfully, the response was
// received successfully, BUT it was a negative response
// from the other node.
printf("This is the error code: %d", response.negative_response_code);
}
} else {
// Some other fatal error ocurred - we weren't able to send
// the request or receive the response. The CAN connection
// may be down.
}
}
}
}
## Dependencies
This library requires 2 dependencies:
* [isotp-c](https://github.com/openxc/isotp-c)
* [bitfield-c](https://github.com/openxc/bitfield-c)
## Testing
The library includes a test suite that uses the `check` C unit test library.
$ make test
You can also see the test coverage if you have `lcov` installed and the
`BROWSER` environment variable set to your choice of web browsers:
$ BROWSER=google-chrome-stable make coverage
## OBD-II Basics
TODO diagram out a request, response and error response
* store the request arb id, mode, pid, and payload locally
* send a can message
* get all new can messages passed to it
* Check the incoming can message to see if it matches one of the standard ECU
response IDs, or our arb ID + 0x8
* if it matches, parse the diagnostic response and call the callback
## Future Notes
you're going to request a few PIDs over and over again at some frequency
you're going to request DTCs once and read the response
you're going to clear DTCs once
we need another layer on top of that to handle the repeated requests.
## Authors
Chris Peplin cpeplin@ford.com
## License
Copyright (c) 2013 Ford Motor Company
Licensed under the BSD license.
|
