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", "value": 45,
44 There may not be a 1:1 relationship between input and output signals - i.e. raw
45 engine timing CAN signals may be summarized in an "engine performance" metric on
46 the abstract side of the interface.
48 The expected format of a single valued message is:
50 {"name": "steering_wheel_angle", "value": 45}
54 The expected format of an event message is:
56 {"name": "button_event", "value": "up", "event": "pressed"}
58 This format is good for something like a button event, where there are two
59 discrete pieces of information in the measurement.
61 ### Raw CAN Message format
63 The format for a raw CAN message:
65 {"bus": 1, "id": 1234, "data": "0x12345678"}
67 **bus** - the numerical identifier of the CAN bus where this message originated,
68 most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
70 **id** - the CAN message ID
72 **data** - up to 8 bytes of data from the CAN message's payload, represented as
73 a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
74 integers, which is why we are not using a numerical data type. Each byte in
75 the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
76 complete string must have an even number of characters.
78 ### Diagnostic Messages
82 A request to add or update a diagnostic request is sent to a vehicle interface
83 with this command format:
85 { "command": "diagnostic_request",
92 "multiple_responses": false,
99 **bus** - the numerical identifier of the CAN bus where this request should be
100 sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
102 **id** - the CAN arbitration ID for the request.
104 **mode** - the OBD-II mode of the request - 1 through 255 (1 through 9 are the
105 standardized modes and 0x22 is a common proprietary mode).
107 **pid** - (optional) the PID for the request, if applicable.
109 **payload** - (optional) up to 7 bytes of data for the request's payload
110 represented as a hexidecimal number in a string. Many JSON parser cannot
111 handle 64-bit integers, which is why we are not using a numerical data type.
112 Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
113 is `0x01` - the complete string must have an even number of characters.
115 **name** - (optional, defaults to nothing) A human readable, string name for
116 this request. If provided, the response will have a `name` field (much like a
117 normal translated message) with this value in place of `bus`, `id`, `mode` and
120 **multiple_responses** - (optional, false by default) if true, request will stay
121 active for a full 100ms, even after receiving a diagnostic response message.
122 This is useful for requests to the functional broadcast arbitration ID
123 (`0x7df`) when you need to get responses from multiple modules. It's possible
124 to set this to `true` for non-broadcast requests, but in practice you won't
125 see any additional responses after the first and it will just take up memory
126 in the VI for longer.
128 **frequency** - (optional, defaults to 0) The frequency in Hz to send this
129 request. To send a single non-recurring request, set this to 0 or leave it
132 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
133 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
134 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
135 OBD-II specification and returned in the `value` field. Set this to `none` to
136 manually override the OBD-II decoding feature for a known PID.
138 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
139 combine to create a unique key to identify a recurring request. This means that
140 you cannot simultaneosly have recurring requests at 2Hz and 5Hz for the same PID
143 If you send a new `diagnostic_request` command with a `bus + id + mode + pid`
144 key matching an existing recurring request, it will update it with whatever
145 other parameters you've provided (e.g. it will change the frequency if you
148 To cancel a recurring request, send a `diagnostic_request` command with the
149 matching request information (i.e. the `bus`, `id`, `mode` and `pid`) but a
152 Non-recurring requests may have the same `bus+id+mode(+pid)` key as a recurring
153 request, and they will co-exist without issue. As soon as a non-recurring
154 request is either completed or times out, it is removed from the active list.
156 If you're just requesting a PID, you can use this minimal field set for the
159 {"bus": 1, "id": 1234, "mode": 1, "pid": 5}
163 The response to a successful request:
173 and to an unsuccessful request, with the `negative_response_code` and no `pid`
180 "negative_response_code": 17}
182 **bus** - the numerical identifier of the CAN bus where this response was
185 **id** - the CAN arbitration ID for this response.
187 **mode** - the OBD-II mode of the original diagnostic request.
189 **pid** - (optional) the PID for the request, if applicable.
191 **success** - true if the response received was a positive response. If this
192 field is false, the remote node returned an error and the
193 `negative_response_code` field should be populated.
195 **negative_response_code** - (optional) If requested node returned an error,
196 `success` will be `false` and this field will contain the negative response
199 Finally, the `payload` and `value` fields are mutually exclusive:
201 **payload** - (optional) up to 7 bytes of data returned in the response,
202 represented as a hexadecimal number in a string. Many JSON parser cannot
203 handle 64-bit integers, which is why we are not using a numerical data type.
205 **value** - (optional) if the response had a payload, this may be the
206 payload interpreted as an integer.
208 The response to a simple PID request would look like this:
210 {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
216 The `version` command triggers the VI to inject a firmware version identifier
217 response into the outgoing data stream.
221 { "command": "version"}
225 { "command_response": "version", "message": "v6.0-dev (default)"}
229 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
230 MAC address of an included Bluetooth module) into into the outgoing data stream.
234 { "command": "device_id"}
238 { "command_response": "device_id", "message": "0012345678"}
240 ### Trace File Format
242 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
243 separated by newlines (which may be either `\r\n` or `\n`, depending on the
244 platform the trace file was recorded).
246 The first line may be a metadata object, although this is optional:
251 "vehicle_interface_id": "7ABF",
255 "trim": "V6 Premium",
258 "description": "highway drive to work",
259 "driver_name": "TJ Giuli",
260 "vehicle_id": "17N1039247929"
264 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
266 {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
268 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
269 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
273 These signal names are a part of the OpenXC specification, although some
274 manufacturers may support custom message names.
276 * steering_wheel_angle
277 * numerical, -600 to +600 degrees
279 * torque_at_transmission
280 * numerical, -500 to 1500 Nm
283 * numerical, 0 to 16382 RPM
286 * numerical, 0 to 655 km/h (this will be positive even if going in reverse
287 as it's not a velocity, although you can use the gear status to figure out
290 * accelerator_pedal_position
293 * parking_brake_status
294 * boolean, (true == brake engaged)
295 * 1Hz, but sent immediately on change
297 * boolean (True == pedal pressed)
298 * 1Hz, but sent immediately on change
299 * transmission_gear_position
300 * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
301 ninth, tenth, reverse, neutral
302 * 1Hz, but sent immediately on change
303 * gear_lever_position
304 * states: neutral, park, reverse, drive, sport, low, first, second, third,
305 fourth, fifth, sixth, seventh, eighth, ninth, tenth
306 * 1Hz, but sent immediately on change
309 0 to 16777214.000 km, with about .2m resolution
312 * states: off, accessory, run, start
313 * 1Hz, but sent immediately on change
317 * fuel_consumed_since_restart
318 * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
319 restarts, like a trip meter)
322 * Value is State: driver, passenger, rear_left, rear_right.
323 * Event is boolean: true == ajar
324 * 1Hz, but sent immediately on change
326 * boolean, true is on
327 * 1Hz, but sent immediately on change
329 * boolean, true is on
330 * 1Hz, but sent immediately on change
331 * windshield_wiper_status
332 * boolean, true is on
333 * 1Hz, but sent immediately on change
335 * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
338 * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
341 ### Signals from Diagnostics Messages
343 This set of signals is often retreived from OBD-II requests. The units can be
344 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
347 * engine_coolant_temperature
348 * barometric_pressure
349 * commanded_throttle_position
352 * intake_air_temperature
353 * intake_manifold_pressure
357 * accelerator_pedal_position
358 * ethanol_fuel_percentage
359 * engine_oil_temperature
365 Copyright (c) 2012-2014 Ford Motor Company
367 Licensed under the BSD license.
369 [OpenXC]: http://openxcplatform.com