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