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 #### Passthrough CAN Mode
 283
 284 The `passthrough` command controls whether low-level CAN messages are passed
 285 through from the CAN bus through the VI to the output stream. If the CAN
 286 acceptance filter is in bypass mode and passthrough is enabled, the output
 287 stream will include all received CAN messages. If the bypass filter is enabled,
 288 only those CAN messages that have been pre-defined in the firmware are
 289 forwarded.
 290
 291 **Request**
 292
 293     { "command": "passthrough"
 294       "bus": 1,
 295       "enabled": true
 296     }
 297
 298 **Response**
 299
 300 If the bus and mode in the request were recognized, the `status` field in the
 301 response will be `true`. If `false`, the passthrough mode was not changed.
 302
 303     { "command_response": "passthrough", "status": true}
 304
 305 ### Trace File Format
 306
 307 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
 308 separated by newlines (which may be either `\r\n` or `\n`, depending on the
 309 platform the trace file was recorded).
 310
 311 The first line may be a metadata object, although this is optional:
 312
 313 ```
 314 {"metadata": {
 315     "version": "v3.0",
 316     "vehicle_interface_id": "7ABF",
 317     "vehicle": {
 318         "make": "Ford",
 319         "model": "Mustang",
 320         "trim": "V6 Premium",
 321         "year": 2013
 322     },
 323     "description": "highway drive to work",
 324     "driver_name": "TJ Giuli",
 325     "vehicle_id": "17N1039247929"
 326 }
 327 ```
 328
 329 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
 330
 331     {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
 332
 333 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
 334 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
 335
 336 ## Official Signals
 337
 338 These signal names are a part of the OpenXC specification, although some
 339 manufacturers may support custom message names.
 340
 341 * steering_wheel_angle
 342     * numerical, -600 to +600 degrees
 343     * 10Hz
 344 * torque_at_transmission
 345     * numerical, -500 to 1500 Nm
 346     * 10Hz
 347 * engine_speed
 348     * numerical, 0 to 16382 RPM
 349     * 10Hz
 350 * vehicle_speed
 351     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
 352       as it's not a velocity, although you can use the gear status to figure out
 353       direction)
 354     * 10Hz
 355 * accelerator_pedal_position
 356     * percentage
 357     * 10Hz
 358 * parking_brake_status
 359     * boolean, (true == brake engaged)
 360     * 1Hz, but sent immediately on change
 361 * brake_pedal_status
 362     * boolean (True == pedal pressed)
 363     * 1Hz, but sent immediately on change
 364 * transmission_gear_position
 365     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
 366       ninth, tenth, reverse, neutral
 367     * 1Hz, but sent immediately on change
 368 * gear_lever_position
 369     * states: neutral, park, reverse, drive, sport, low, first, second, third,
 370       fourth, fifth, sixth, seventh, eighth, ninth, tenth
 371     * 1Hz, but sent immediately on change
 372 * odometer
 373     * Numerical, km
 374         0 to 16777214.000 km, with about .2m resolution
 375     * 10Hz
 376 * ignition_status
 377     * states: off, accessory, run, start
 378     * 1Hz, but sent immediately on change
 379 * fuel_level
 380     * percentage
 381     * 2Hz
 382 * fuel_consumed_since_restart
 383     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
 384       restarts, like a trip meter)
 385     * 10Hz
 386 * door_status
 387     * Value is State: driver, passenger, rear_left, rear_right.
 388     * Event is boolean: true == ajar
 389     * 1Hz, but sent immediately on change
 390 * headlamp_status
 391     * boolean, true is on
 392     * 1Hz, but sent immediately on change
 393 * high_beam_status
 394     * boolean, true is on
 395     * 1Hz, but sent immediately on change
 396 * windshield_wiper_status
 397     * boolean, true is on
 398     * 1Hz, but sent immediately on change
 399 * latitude
 400     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
 401     * 1Hz
 402 * longitude
 403     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
 404     * 1Hz
 405
 406 ### Signals from Diagnostics Messages
 407
 408 This set of signals is often retreived from OBD-II requests. The units can be
 409 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
 410
 411 * engine_load
 412 * engine_coolant_temperature
 413 * barometric_pressure
 414 * commanded_throttle_position
 415 * throttle_position
 416 * fuel_level
 417 * intake_air_temperature
 418 * intake_manifold_pressure
 419 * running_time
 420 * fuel_pressure
 421 * mass_airflow
 422 * accelerator_pedal_position
 423 * ethanol_fuel_percentage
 424 * engine_oil_temperature
 425 * engine_torque
 426
 427 License
 428 =======
 429
 430 Copyright (c) 2012-2014 Ford Motor Company
 431
 432 Licensed under the BSD license.
 433
 434 [OpenXC]: http://openxcplatform.com