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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
# OpenXC Message Format Specification
This specification is a part of the [OpenXC platform][OpenXC].
An OpenXC vehicle interface sends generic vehicle data over one or more output
interfaces (e.g. USB or Bluetooth) as JSON objects, separated by newlines.
There are two valid message types - single valued and evented.
There may not be a 1:1 relationship between input and output signals - i.e. raw
engine timing CAN signals may be summarized in an "engine performance" metric on
the abstract side of the interface.
## Single Valued
The expected format of a single valued message is:
{"name": "steering_wheel_angle", "value": 45}
## Evented
The expected format of an event message is:
{"name": "button_event", "value": "up", "event": "pressed"}
This format is good for something like a button event, where there are two
discrete pieces of information in the measurement.
## Raw CAN Message format
An OpenXC vehicle interface may also output raw CAN messages. Each CAN message
is sent as a JSON object, separated by newlines. The format of each object is:
{"bus": 1, "id": 1234, "value": "0x12345678"}
**bus** - the numerical identifier of the CAN bus where this message originated,
most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
**id** - the CAN message ID
**data** - up to 8 bytes of data from the CAN message's payload, represented as
a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
integers, which is why we are not using a numerical data type. Each byte in
the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
complete string must have an even number of characters.
## Diagnostic Messages
### Requests
A request to add or update a diagnostic request is sent to a vehicle interface
with this command format:
{ "command": "diagnostic_request",
"request": {
"bus": 1,
"id": 1234,
"mode": 1,
"pid": 5,
"payload": "0x1234",
"parse_payload": true,
"multiple_responses": false,
"factor": 1.0,
"offset": 0,
"frequency": 1,
"name": "my_pid"
}
}
}
**bus** - the numerical identifier of the CAN bus where this request should be
sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
**id** - the CAN arbitration ID for the request.
**mode** - the OBD-II mode of the request - 1 through 15 (1 through 9 are the
standardized modes).
**pid** - (optional) the PID for the request, if applicable.
**payload** - (optional) up to 7 bytes of data for the request's payload
represented as a hexidecimal number in a string. Many JSON parser cannot
handle 64-bit integers, which is why we are not using a numerical data type.
Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
is `0x01` - the complete string must have an even number of characters.
**parse_payload** - (optional, false by default) if `true`, the complete payload
in the response message will be parsed as a number and returned in the
`value` field of the response. The `payload` field will be omitted in
responses with a `value`.
**name** - (optional, defaults to nothing) A human readable, string name for
this request. If provided, the response will have a `name` field (much like a
normal translated message) with this value in place of `bus`, `id`, `mode` and
`pid`.
**multiple_responses** - (optional, false by default) if true, request will stay
active for a full 100ms, even after receiving a diagnostic response message.
This is useful for requests to the functional broadcast arbitration ID
(`0x7df`) when you need to get responses from multiple modules. It's possible
to set this to `true` for non-broadcast requests, but in practice you won't
see any additional responses after the first and it will just take up memory
in the VI for longer.
**factor** - (optional, 1.0 by default) if `parse_payload` is true, the value in
the payload will be multiplied by this factor before returning. The `factor`
is applied before the `offset`.
**offset** - (optional, 0 by default) if `parse_payload` is true, this offset
will be added to the value in the payload before returning. The `offset` is
applied after the `factor`.
**frequency** - (optional, defaults to 0) The frequency in Hz to send this
request. To send a single request, set this to 0 or leave it out.
The `bus+id+mode+pid` key is unique, so if you send a create request with that
key twice, it'll overwrite the existing one (i.e. it will change the frequency,
the only other parameter). To cancel a recurring request, send this command with
the frequency set to 0.
If you're just requesting a PID, you can use this minimal field set for the
`request` object:
{"bus": 1, "id": 1234, "mode": 1, "pid": 5}
### Responses
The response to a successful request:
{"bus": 1,
"id": 1234,
"mode": 1,
"pid": 5,
"success": true,
"payload": "0x1234",
"value": 4660}
and to an unsuccessful request, with the `negative_response_code` and no `pid`
echo:
{"bus": 1,
"id": 1234,
"mode": 1,
"success": false,
"negative_response_code": 17}
**bus** - the numerical identifier of the CAN bus where this response was
received.
**id** - the CAN arbitration ID for this response.
**mode** - the OBD-II mode of the original diagnostic request.
**pid** - (optional) the PID for the request, if applicable.
**success** - true if the response received was a positive response. If this
field is false, the remote node returned an error and the
`negative_response_code` field should be populated.
**negative_response_code** - (optional) If requested node returned an error,
`success` will be `false` and this field will contain the negative response
code (NRC).
Finally, the `payload` and `value` fields are mutually exclusive:
**payload** - (optional) up to 7 bytes of data returned in the response,
represented as a hexadecimal number in a string. Many JSON parser cannot
handle 64-bit integers, which is why we are not using a numerical data type.
**value** - (optional) if the response had a payload, this may be the
payload interpreted as an integer and transformed with a factor and offset
provided with the request.
The response to a simple PID request would look like this:
{"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
## Commands
### Version Query
The `version` command triggers the VI to inject a firmware version identifier
response into the outgoing data stream.
**Request**
{ "command": "version"}
**Response**
{ "command_response": "version", "message": "v6.0-dev (default)"}
### Device ID Query
The `device_id` command triggers the VI to inject a unique device ID (e.g. the
MAC address of an included Bluetooth module) into into the outgoing data stream.
**Request**
{ "command": "device_id"}
**Response**
{ "command_response": "device_id", "message": "0012345678"}
## Trace File Format
An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
separated by newlines.
The first line may be a metadata object, although this is optional:
```
{"metadata": {
"version": "v3.0",
"vehicle_interface_id": "7ABF",
"vehicle": {
"make": "Ford",
"model": "Mustang",
"trim": "V6 Premium",
"year": 2013
},
"description": "highway drive to work",
"driver_name": "TJ Giuli",
"vehicle_id": "17N1039247929"
}
```
The following lines are OpenXC messages with a `timestamp` field added, e.g.:
{"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
(i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
## Official Signals
These signal names are a part of the OpenXC specification, although some
manufacturers may support custom message names.
* steering_wheel_angle
* numerical, -600 to +600 degrees
* 10Hz
* torque_at_transmission
* numerical, -500 to 1500 Nm
* 10Hz
* engine_speed
* numerical, 0 to 16382 RPM
* 10Hz
* vehicle_speed
* numerical, 0 to 655 km/h (this will be positive even if going in reverse
as it's not a velocity, although you can use the gear status to figure out
direction)
* 10Hz
* accelerator_pedal_position
* percentage
* 10Hz
* parking_brake_status
* boolean, (true == brake engaged)
* 1Hz, but sent immediately on change
* brake_pedal_status
* boolean (True == pedal pressed)
* 1Hz, but sent immediately on change
* transmission_gear_position
* states: first, second, third, fourth, fifth, sixth, seventh, eighth,
reverse, neutral
* 1Hz, but sent immediately on change
* gear_lever_position
* states: neutral, park, reverse, drive, sport, low, first, second, third,
fourth, fifth, sixth
* 1Hz, but sent immediately on change
* odometer
* Numerical, km
0 to 16777214.000 km, with about .2m resolution
* 10Hz
* ignition_status
* states: off, accessory, run, start
* 1Hz, but sent immediately on change
* fuel_level
* percentage
* 2Hz
* fuel_consumed_since_restart
* numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
restarts, like a trip meter)
* 10Hz
* door_status
* Value is State: driver, passenger, rear_left, rear_right.
* Event is boolean: true == ajar
* 1Hz, but sent immediately on change
* headlamp_status
* boolean, true is on
* 1Hz, but sent immediately on change
* high_beam_status
* boolean, true is on
* 1Hz, but sent immediately on change
* windshield_wiper_status
* boolean, true is on
* 1Hz, but sent immediately on change
* latitude
* numerical, -89.0 to 89.0 degrees with standard GPS accuracy
* 1Hz
* longitude
* numerical, -179.0 to 179.0 degrees with standard GPS accuracy
* 1Hz
License
=======
Copyright (c) 2012-2013 Ford Motor Company
Licensed under the BSD license.
[OpenXC]: http://openxcplatform.com
|