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