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