1 # OpenXC Message Format Specification
5 This specification is a part of the [OpenXC platform][OpenXC].
7 An OpenXC vehicle interface sends generic vehicle data over one or more output
8 interfaces (e.g. USB or Bluetooth) as JSON or Protocol Buffers (protobuf).
10 ## Binary (Protocol Buffers)
12 The binary format is encoded using [Google Protocol
13 Buffers](https://code.google.com/p/protobuf/). The format is specified in the
14 file `openxc.proto`. Those are published using the standard length-delimited
15 method (any protobuf library should support this).
17 The binary format is best if you need to maximize the amount of data that can be
18 sent from the VI, trading off flexibility for efficiency.
22 This document describes the JSON format and includes a high level description of
23 each type and field. Each JSON message published by a VI is delimited with a
26 The JSON format is best for most developers, as it is fairly efficient and very
31 Any of the following JSON objects may optionally include an `extras`
32 field. The value may be any valid JSON object or array. The client libraries
33 will do their best to parse this information into a generic format and pass it
34 to your application. For example:
36 {"name": "steering_wheel_angle",
45 There may not be a 1:1 relationship between input and output signals - i.e. raw
46 engine timing CAN signals may be summarized in an "engine performance" metric on
47 the abstract side of the interface.
49 The expected format of a single valued message is:
51 {"name": "steering_wheel_angle", "value": 45}
55 The expected format of an event message is:
57 {"name": "button_event", "value": "up", "event": "pressed"}
59 This format is good for something like a button event, where there are two
60 discrete pieces of information in the measurement.
62 ### Raw CAN Message format
64 The format for a raw CAN message:
66 {"bus": 1, "id": 1234, "data": "0x12345678"}
68 **bus** - the numerical identifier of the CAN bus where this message originated,
69 most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
71 **id** - the CAN message ID
73 **data** - up to 8 bytes of data from the CAN message's payload, represented as
74 a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
75 integers, which is why we are not using a numerical data type. Each byte in
76 the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
77 complete string must have an even number of characters.
79 ### Diagnostic Messages
83 A diagnostic request is created, update and deleted with a JSON object like this
86 { "command": "diagnostic_request",
94 "multiple_responses": false,
101 * The `command` must be `diagnostic_request.`
102 * The `action` must be included, and must be one of:
103 * `create` - create a new one-off or recurring diagnostic request.
104 * `update` - update an existing request.
105 * `delete` - delete an existing request.
106 * The details of the request must be included in the `request` field, using
107 the sub-fields defined below.
109 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
110 combine to create a unique key to identify a request. These four fields will be
111 referred to as the key of the diagnostic request. For example, to create a
112 simple one-time diagnostic request:
114 { "command": "diagnostic_request",
125 Requests are completed after any responses are received (unless
126 `multiple_responses` is set), or the request has timed out after a certain
127 number of seconds. After a request is completed, you can re-`create` the same
128 key to make another request.
130 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
131 previous example as a recurring request at 1Hz:
133 { "command": "diagnostic_request",
145 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
147 { "command": "diagnostic_request",
158 To update one of the fields of a recurring request, send an `update` action with
159 the same key, plus the field to update. For example, to change the frequency of
160 the example request to 2Hz:
162 { "command": "diagnostic_request",
174 Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
175 *and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
176 exist in parallel with a recurring request for the same key.
178 **bus** - the numerical identifier of the CAN bus where this request should be
179 sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
181 **id** - the CAN arbitration ID for the request.
183 **mode** - the OBD-II mode of the request - 1 through 255 (1 through 9 are the
184 standardized modes and 0x22 is a common proprietary mode).
186 **pid** - (optional) the PID for the request, if applicable.
188 **payload** - (optional) up to 7 bytes of data for the request's payload
189 represented as a hexadecimal number in a string. Many JSON parser cannot
190 handle 64-bit integers, which is why we are not using a numerical data type.
191 Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
192 is `0x01` - the complete string must have an even number of characters.
194 **name** - (optional, defaults to nothing) A human readable, string name for
195 this request. If provided, the response will have a `name` field (much like a
196 normal translated message) with this value in place of `bus`, `id`, `mode` and
199 **multiple_responses** - (optional, false by default) if true, request will stay
200 active for a full 100ms, even after receiving a diagnostic response message.
201 This is useful for requests to the functional broadcast arbitration ID
202 (`0x7df`) when you need to get responses from multiple modules. It's possible
203 to set this to `true` for non-broadcast requests, but in practice you won't
204 see any additional responses after the first and it will just take up memory
205 in the VI for longer.
207 **frequency** - (optional) Make this request a recurring request, at a this
208 frequency in Hz. To send a single non-recurring request, leave this field out.
210 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
211 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
212 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
213 OBD-II specification and returned in the `value` field. Set this to `none` to
214 manually override the OBD-II decoding feature for a known PID.
218 The response to a successful request:
228 and to an unsuccessful request, with the `negative_response_code` and no `pid`
235 "negative_response_code": 17}
237 **bus** - the numerical identifier of the CAN bus where this response was
240 **id** - the CAN arbitration ID for this response.
242 **mode** - the OBD-II mode of the original diagnostic request.
244 **pid** - (optional) the PID for the request, if applicable.
246 **success** - true if the response received was a positive response. If this
247 field is false, the remote node returned an error and the
248 `negative_response_code` field should be populated.
250 **negative_response_code** - (optional) If requested node returned an error,
251 `success` will be `false` and this field will contain the negative response
254 Finally, the `payload` and `value` fields are mutually exclusive:
256 **payload** - (optional) up to 7 bytes of data returned in the response,
257 represented as a hexadecimal number in a string. Many JSON parser cannot
258 handle 64-bit integers, which is why we are not using a numerical data type.
260 **value** - (optional) if the response had a payload, this may be the
261 payload interpreted as an integer.
263 The response to a simple PID request would look like this:
265 {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
269 In addition to the `diagnostic_request` command described earlier, there are
270 other possible values for the `command` field.
274 The `version` command triggers the VI to inject a firmware version identifier
275 response into the outgoing data stream.
279 { "command": "version"}
283 { "command_response": "version", "message": "v6.0-dev (default)"}
287 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
288 MAC address of an included Bluetooth module) into into the outgoing data stream.
292 { "command": "device_id"}
296 { "command_response": "device_id", "message": "0012345678"}
298 ### Trace File Format
300 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
301 separated by newlines (which may be either `\r\n` or `\n`, depending on the
302 platform the trace file was recorded).
304 The first line may be a metadata object, although this is optional:
309 "vehicle_interface_id": "7ABF",
313 "trim": "V6 Premium",
316 "description": "highway drive to work",
317 "driver_name": "TJ Giuli",
318 "vehicle_id": "17N1039247929"
322 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
324 {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
326 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
327 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
331 These signal names are a part of the OpenXC specification, although some
332 manufacturers may support custom message names.
334 * steering_wheel_angle
335 * numerical, -600 to +600 degrees
337 * torque_at_transmission
338 * numerical, -500 to 1500 Nm
341 * numerical, 0 to 16382 RPM
344 * numerical, 0 to 655 km/h (this will be positive even if going in reverse
345 as it's not a velocity, although you can use the gear status to figure out
348 * accelerator_pedal_position
351 * parking_brake_status
352 * boolean, (true == brake engaged)
353 * 1Hz, but sent immediately on change
355 * boolean (True == pedal pressed)
356 * 1Hz, but sent immediately on change
357 * transmission_gear_position
358 * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
359 ninth, tenth, reverse, neutral
360 * 1Hz, but sent immediately on change
361 * gear_lever_position
362 * states: neutral, park, reverse, drive, sport, low, first, second, third,
363 fourth, fifth, sixth, seventh, eighth, ninth, tenth
364 * 1Hz, but sent immediately on change
367 0 to 16777214.000 km, with about .2m resolution
370 * states: off, accessory, run, start
371 * 1Hz, but sent immediately on change
375 * fuel_consumed_since_restart
376 * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
377 restarts, like a trip meter)
380 * Value is State: driver, passenger, rear_left, rear_right.
381 * Event is boolean: true == ajar
382 * 1Hz, but sent immediately on change
384 * boolean, true is on
385 * 1Hz, but sent immediately on change
387 * boolean, true is on
388 * 1Hz, but sent immediately on change
389 * windshield_wiper_status
390 * boolean, true is on
391 * 1Hz, but sent immediately on change
393 * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
396 * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
399 ### Signals from Diagnostics Messages
401 This set of signals is often retreived from OBD-II requests. The units can be
402 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
405 * engine_coolant_temperature
406 * barometric_pressure
407 * commanded_throttle_position
410 * intake_air_temperature
411 * intake_manifold_pressure
415 * accelerator_pedal_position
416 * ethanol_fuel_percentage
417 * engine_oil_temperature
423 Copyright (c) 2012-2014 Ford Motor Company
425 Licensed under the BSD license.
427 [OpenXC]: http://openxcplatform.com