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