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