README.md

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