README.md

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