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