README.md

   1 # OpenXC Message Format Specification
   2
   3 This specification is a part of the [OpenXC platform][OpenXC].
   4
   5 An OpenXC vehicle interface sends generic vehicle data over one or more output
   6 interfaces (e.g. USB or Bluetooth) as JSON objects, separated by newlines.
   7
   8 There are two valid message types - single valued and evented.
   9
  10 There may not be a 1:1 relationship between input and output signals - i.e. raw
  11 engine timing CAN signals may be summarized in an "engine performance" metric on
  12 the abstract side of the interface.
  13
  14 ## Single Valued
  15
  16 The expected format of a single valued message is:
  17
  18     {"name": "steering_wheel_angle", "value": 45}
  19
  20 ## Evented
  21
  22 The expected format of an event message is:
  23
  24     {"name": "button_event", "value": "up", "event": "pressed"}
  25
  26 This format is good for something like a button event, where there are two
  27 discrete pieces of information in the measurement.
  28
  29 ## Raw CAN Message format
  30
  31 An OpenXC vehicle interface may also output raw CAN messages. Each CAN message
  32 is sent as a JSON object, separated by newlines. The format of each object is:
  33
  34     {"bus": 1, "id": 1234, "value": "0x12345678"}
  35
  36 **bus** - the numerical identifier of the CAN bus where this message originated,
  37   most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
  38
  39 **id** - the CAN message ID
  40
  41 **data** - up to 8 bytes of data from the CAN message's payload, represented as
  42   a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
  43   integers, which is why we are not using a numerical data type. Each byte in
  44   the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
  45   complete string must have an even number of characters.
  46
  47 ## Diagnostic Messages
  48
  49 ### Requests
  50
  51 A request to add or update a diagnostic request is sent to a vehicle interface
  52 with this command format:
  53
  54     { "command": "diagnostic_request",
  55       "request": {
  56           "bus": 1,
  57           "id": 1234,
  58           "mode": 1,
  59           "pid": 5,
  60           "payload": "0x1234",
  61           "multiple_responses": false,
  62           "factor": 1.0,
  63           "offset": 0,
  64           "frequency": 1,
  65           "name": "my_pid"
  66         }
  67       }
  68     }
  69
  70 **bus** - the numerical identifier of the CAN bus where this request should be
  71     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
  72
  73 **id** - the CAN arbitration ID for the request.
  74
  75 **mode** - the OBD-II mode of the request - 1 through 15 (1 through 9 are the
  76     standardized modes).
  77
  78 **pid** - (optional) the PID for the request, if applicable.
  79
  80 **payload** - (optional) up to 7 bytes of data for the request's payload
  81     represented as a hexidecimal number in a string. Many JSON parser cannot
  82     handle 64-bit integers, which is why we are not using a numerical data type.
  83     Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
  84     is `0x01` - the complete string must have an even number of characters.
  85
  86 **name** - (optional, defaults to nothing) A human readable, string name for
  87   this request. If provided, the response will have a `name` field (much like a
  88   normal translated message) with this value in place of `bus`, `id`, `mode` and
  89   `pid`.
  90
  91 **multiple_responses** - (optional, false by default) if true, request will stay
  92   active for a full 100ms, even after receiving a diagnostic response message.
  93   This is useful for requests to the functional broadcast arbitration ID
  94   (`0x7df`) when you need to get responses from multiple modules. It's possible
  95   to set this to `true` for non-broadcast requests, but in practice you won't
  96   see any additional responses after the first and it will just take up memory
  97   in the VI for longer.
  98
  99 **frequency** - (optional, defaults to 0) The frequency in Hz to send this
 100     request. To send a single non-recurring request, set this to 0 or leave it
 101     out.
 102
 103 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
 104 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
 105 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
 106 OBD-II specification and returned in the `value` field. Set this to `none` to
 107 manually override the OBD-II decoding feature for a known PID.
 108
 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 recurring request. This means that
 111 you cannot simultaneosly have recurring requests at 2Hz and 5Hz for the same PID
 112 from the same ID.
 113
 114 If you send a new `diagnostic_request` command with a `bus + id + mode + pid`
 115 key matching an existing recurring request, it will update it with whatever
 116 other parameters you've provided (e.g. it will change the frequency if you
 117 specify one).
 118
 119 To cancel a recurring request, send a `diagnostic_request` command with the
 120 matching request information (i.e. the `bus`, `id`, `mode` and `pid`) but a
 121 frequency of 0.
 122
 123 Non-recurring requests may have the same `bus+id+mode(+pid)` key as a recurring
 124 request, and they will co-exist without issue. As soon as a non-recurring
 125 request is either completed or times out, it is removed from the active list.
 126
 127 If you're just requesting a PID, you can use this minimal field set for the
 128 `request` object:
 129
 130     {"bus": 1, "id": 1234, "mode": 1, "pid": 5}
 131
 132 ### Responses
 133
 134 The response to a successful request:
 135
 136     {"bus": 1,
 137       "id": 1234,
 138       "mode": 1,
 139       "pid": 5,
 140       "success": true,
 141       "payload": "0x1234",
 142       "value": 4660}
 143
 144 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 145 echo:
 146
 147     {"bus": 1,
 148       "id": 1234,
 149       "mode": 1,
 150       "success": false,
 151       "negative_response_code": 17}
 152
 153 **bus** - the numerical identifier of the CAN bus where this response was
 154     received.
 155
 156 **id** - the CAN arbitration ID for this response.
 157
 158 **mode** - the OBD-II mode of the original diagnostic request.
 159
 160 **pid** - (optional) the PID for the request, if applicable.
 161
 162 **success** -  true if the response received was a positive response. If this
 163   field is false, the remote node returned an error and the
 164   `negative_response_code` field should be populated.
 165
 166 **negative_response_code** - (optional)  If requested node returned an error,
 167     `success` will be `false` and this field will contain the negative response
 168     code (NRC).
 169
 170 Finally, the `payload` and `value` fields are mutually exclusive:
 171
 172 **payload** - (optional) up to 7 bytes of data returned in the response,
 173     represented as a hexadecimal number in a string. Many JSON parser cannot
 174     handle 64-bit integers, which is why we are not using a numerical data type.
 175
 176 **value** - (optional) if the response had a payload, this may be the
 177     payload interpreted as an integer.
 178
 179 The response to a simple PID request would look like this:
 180
 181     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 182
 183 ## Commands
 184
 185 ### Version Query
 186
 187 The `version` command triggers the VI to inject a firmware version identifier
 188 response into the outgoing data stream.
 189
 190 **Request**
 191
 192     { "command": "version"}
 193
 194 **Response**
 195
 196     { "command_response": "version", "message": "v6.0-dev (default)"}
 197
 198 ### Device ID Query
 199
 200 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 201 MAC address of an included Bluetooth module) into into the outgoing data stream.
 202
 203 **Request**
 204
 205     { "command": "device_id"}
 206
 207 **Response**
 208
 209     { "command_response": "device_id", "message": "0012345678"}
 210
 211 ## Trace File Format
 212
 213 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
 214 separated by newlines.
 215
 216 The first line may be a metadata object, although this is optional:
 217
 218 ```
 219 {"metadata": {
 220     "version": "v3.0",
 221     "vehicle_interface_id": "7ABF",
 222     "vehicle": {
 223         "make": "Ford",
 224         "model": "Mustang",
 225         "trim": "V6 Premium",
 226         "year": 2013
 227     },
 228     "description": "highway drive to work",
 229     "driver_name": "TJ Giuli",
 230     "vehicle_id": "17N1039247929"
 231 }
 232 ```
 233
 234 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
 235
 236     {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
 237
 238 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
 239 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
 240
 241 ## Official Signals
 242
 243 These signal names are a part of the OpenXC specification, although some
 244 manufacturers may support custom message names.
 245
 246 * steering_wheel_angle
 247     * numerical, -600 to +600 degrees
 248     * 10Hz
 249 * torque_at_transmission
 250     * numerical, -500 to 1500 Nm
 251     * 10Hz
 252 * engine_speed
 253     * numerical, 0 to 16382 RPM
 254     * 10Hz
 255 * vehicle_speed
 256     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
 257       as it's not a velocity, although you can use the gear status to figure out
 258       direction)
 259     * 10Hz
 260 * accelerator_pedal_position
 261     * percentage
 262     * 10Hz
 263 * parking_brake_status
 264     * boolean, (true == brake engaged)
 265     * 1Hz, but sent immediately on change
 266 * brake_pedal_status
 267     * boolean (True == pedal pressed)
 268     * 1Hz, but sent immediately on change
 269 * transmission_gear_position
 270     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
 271       reverse, neutral
 272     * 1Hz, but sent immediately on change
 273 * gear_lever_position
 274     * states: neutral, park, reverse, drive, sport, low, first, second, third,
 275       fourth, fifth, sixth
 276     * 1Hz, but sent immediately on change
 277 * odometer
 278     * Numerical, km
 279         0 to 16777214.000 km, with about .2m resolution
 280     * 10Hz
 281 * ignition_status
 282     * states: off, accessory, run, start
 283     * 1Hz, but sent immediately on change
 284 * fuel_level
 285     * percentage
 286     * 2Hz
 287 * fuel_consumed_since_restart
 288     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
 289       restarts, like a trip meter)
 290     * 10Hz
 291 * door_status
 292     * Value is State: driver, passenger, rear_left, rear_right.
 293     * Event is boolean: true == ajar
 294     * 1Hz, but sent immediately on change
 295 * headlamp_status
 296     * boolean, true is on
 297     * 1Hz, but sent immediately on change
 298 * high_beam_status
 299     * boolean, true is on
 300     * 1Hz, but sent immediately on change
 301 * windshield_wiper_status
 302     * boolean, true is on
 303     * 1Hz, but sent immediately on change
 304 * latitude
 305     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
 306     * 1Hz
 307 * longitude
 308     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
 309     * 1Hz
 310
 311 License
 312 =======
 313
 314 Copyright (c) 2012-2013 Ford Motor Company
 315
 316 Licensed under the BSD license.
 317
 318 [OpenXC]: http://openxcplatform.com