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