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 An OpenXC vehicle interface may also output raw CAN messages. Each CAN message
  38 is sent as a JSON object, separated by newlines. The format of each object is:
  39
  40     {"bus": 1, "id": 1234, "value": "0x12345678"}
  41
  42 **bus** - the numerical identifier of the CAN bus where this message originated,
  43   most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
  44
  45 **id** - the CAN message ID
  46
  47 **data** - up to 8 bytes of data from the CAN message's payload, represented as
  48   a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
  49   integers, which is why we are not using a numerical data type. Each byte in
  50   the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
  51   complete string must have an even number of characters.
  52
  53 ## Diagnostic Messages
  54
  55 ### Requests
  56
  57 A request to add or update a diagnostic request is sent to a vehicle interface
  58 with this command format:
  59
  60     { "command": "diagnostic_request",
  61       "request": {
  62           "bus": 1,
  63           "id": 1234,
  64           "mode": 1,
  65           "pid": 5,
  66           "payload": "0x1234",
  67           "multiple_responses": false,
  68           "factor": 1.0,
  69           "offset": 0,
  70           "frequency": 1,
  71           "name": "my_pid"
  72         }
  73       }
  74     }
  75
  76 **bus** - the numerical identifier of the CAN bus where this request should be
  77     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
  78
  79 **id** - the CAN arbitration ID for the request.
  80
  81 **mode** - the OBD-II mode of the request - 1 through 15 (1 through 9 are the
  82     standardized modes).
  83
  84 **pid** - (optional) the PID for the request, if applicable.
  85
  86 **payload** - (optional) up to 7 bytes of data for the request's payload
  87     represented as a hexidecimal number in a string. Many JSON parser cannot
  88     handle 64-bit integers, which is why we are not using a numerical data type.
  89     Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
  90     is `0x01` - the complete string must have an even number of characters.
  91
  92 **name** - (optional, defaults to nothing) A human readable, string name for
  93   this request. If provided, the response will have a `name` field (much like a
  94   normal translated message) with this value in place of `bus`, `id`, `mode` and
  95   `pid`.
  96
  97 **multiple_responses** - (optional, false by default) if true, request will stay
  98   active for a full 100ms, even after receiving a diagnostic response message.
  99   This is useful for requests to the functional broadcast arbitration ID
 100   (`0x7df`) when you need to get responses from multiple modules. It's possible
 101   to set this to `true` for non-broadcast requests, but in practice you won't
 102   see any additional responses after the first and it will just take up memory
 103   in the VI for longer.
 104
 105 **frequency** - (optional, defaults to 0) The frequency in Hz to send this
 106     request. To send a single non-recurring request, set this to 0 or leave it
 107     out.
 108
 109 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
 110 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
 111 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
 112 OBD-II specification and returned in the `value` field. Set this to `none` to
 113 manually override the OBD-II decoding feature for a known PID.
 114
 115 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
 116 combine to create a unique key to identify a recurring request. This means that
 117 you cannot simultaneosly have recurring requests at 2Hz and 5Hz for the same PID
 118 from the same ID.
 119
 120 If you send a new `diagnostic_request` command with a `bus + id + mode + pid`
 121 key matching an existing recurring request, it will update it with whatever
 122 other parameters you've provided (e.g. it will change the frequency if you
 123 specify one).
 124
 125 To cancel a recurring request, send a `diagnostic_request` command with the
 126 matching request information (i.e. the `bus`, `id`, `mode` and `pid`) but a
 127 frequency of 0.
 128
 129 Non-recurring requests may have the same `bus+id+mode(+pid)` key as a recurring
 130 request, and they will co-exist without issue. As soon as a non-recurring
 131 request is either completed or times out, it is removed from the active list.
 132
 133 If you're just requesting a PID, you can use this minimal field set for the
 134 `request` object:
 135
 136     {"bus": 1, "id": 1234, "mode": 1, "pid": 5}
 137
 138 ### Responses
 139
 140 The response to a successful request:
 141
 142     {"bus": 1,
 143       "id": 1234,
 144       "mode": 1,
 145       "pid": 5,
 146       "success": true,
 147       "payload": "0x1234",
 148       "value": 4660}
 149
 150 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 151 echo:
 152
 153     {"bus": 1,
 154       "id": 1234,
 155       "mode": 1,
 156       "success": false,
 157       "negative_response_code": 17}
 158
 159 **bus** - the numerical identifier of the CAN bus where this response was
 160     received.
 161
 162 **id** - the CAN arbitration ID for this response.
 163
 164 **mode** - the OBD-II mode of the original diagnostic request.
 165
 166 **pid** - (optional) the PID for the request, if applicable.
 167
 168 **success** -  true if the response received was a positive response. If this
 169   field is false, the remote node returned an error and the
 170   `negative_response_code` field should be populated.
 171
 172 **negative_response_code** - (optional)  If requested node returned an error,
 173     `success` will be `false` and this field will contain the negative response
 174     code (NRC).
 175
 176 Finally, the `payload` and `value` fields are mutually exclusive:
 177
 178 **payload** - (optional) up to 7 bytes of data returned in the response,
 179     represented as a hexadecimal number in a string. Many JSON parser cannot
 180     handle 64-bit integers, which is why we are not using a numerical data type.
 181
 182 **value** - (optional) if the response had a payload, this may be the
 183     payload interpreted as an integer.
 184
 185 The response to a simple PID request would look like this:
 186
 187     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 188
 189 ## Commands
 190
 191 ### Version Query
 192
 193 The `version` command triggers the VI to inject a firmware version identifier
 194 response into the outgoing data stream.
 195
 196 **Request**
 197
 198     { "command": "version"}
 199
 200 **Response**
 201
 202     { "command_response": "version", "message": "v6.0-dev (default)"}
 203
 204 ### Device ID Query
 205
 206 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 207 MAC address of an included Bluetooth module) into into the outgoing data stream.
 208
 209 **Request**
 210
 211     { "command": "device_id"}
 212
 213 **Response**
 214
 215     { "command_response": "device_id", "message": "0012345678"}
 216
 217 ## Trace File Format
 218
 219 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
 220 separated by newlines.
 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       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
 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 License
 318 =======
 319
 320 Copyright (c) 2012-2013 Ford Motor Company
 321
 322 Licensed under the BSD license.
 323
 324 [OpenXC]: http://openxcplatform.com