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