README.md

   1 # OpenXC Message Format Specification
   2
   3 Version: v0.6.0
   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 ## JSON
  11
  12 The JSON format is the most flexible and easiest to use. The format is fully
  13 specified in the [JSON.mkd](JSON.mkd) file in this repository.
  14 a more flexible option than binary, but is less compact and
  15 therefore takes more bandwidth and processing power.
  16
  17 The JSON format is best for most developers, as it is fairly efficient and very
  18 flexible.
  19
  20 ## Binary (Protocol Buffers)
  21
  22 The binary format is encoded using [Google Protocol
  23 Buffers](https://code.google.com/p/protobuf/). The format is specified in the
  24 file [openxc.proto](openxc.proto). The descriptions of the messages can be foud
  25 in the JSON specs - the binary format mirrors this.
  26
  27 The binary messages are published by the VI using the standard length-delimited
  28 method (any protobuf library should support this).
  29
  30 The binary format is best if you need to maximize the amount of data that can be
  31 sent from the VI, trading off flexibility for efficiency.
  32
  33 ## Message Pack
  34 MessagePack is an efficient binary serialization format. It lets you exchange data
  35 among multiple languages like JSON, but it's faster and smaller. Small integers are
  36 encoded into a single byte, and typical short strings require only one extra byte
  37 in addition to the strings themselves
  38
  39 For protocol specification visit:
  40 https://github.com/msgpack/msgpack/blob/master/spec.md
  41
  42 We are using the following lib:
  43 https://github.com/camgunz/cmp
  44
  45 MessagePack provides a binary alternative to ProtoBuf. There are pros & cons to each
  46 so you can decide what works best for your project.
  47
  48 ## Trace File Format
  49
  50 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
  51 separated by newlines (which may be either `\r\n` or `\n`, depending on the
  52 platform the trace file was recorded).
  53
  54 The first line may be a metadata object, although this is optional:
  55
  56 ```
  57 {"metadata": {
  58     "version": "v3.0",
  59     "vehicle_interface_id": "7ABF",
  60     "vehicle": {
  61         "make": "Ford",
  62         "model": "Mustang",
  63         "trim": "V6 Premium",
  64         "year": 2013
  65     },
  66     "description": "highway drive to work",
  67     "driver_name": "TJ Giuli",
  68     "vehicle_id": "17N1039247929"
  69 }
  70 ```
  71
  72 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
  73
  74     {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
  75
  76 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
  77 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
  78
  79 ## Official Signals
  80
  81 These signal names are a part of the OpenXC specification, although some
  82 manufacturers may support custom message names.
  83
  84 * steering_wheel_angle
  85     * numerical, -600 to +600 degrees
  86     * 10Hz
  87 * torque_at_transmission
  88     * numerical, -500 to 1500 Nm
  89     * 10Hz
  90 * engine_speed
  91     * numerical, 0 to 16382 RPM
  92     * 10Hz
  93 * vehicle_speed
  94     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
  95       as it's not a velocity, although you can use the gear status to figure out
  96       direction)
  97     * 10Hz
  98 * accelerator_pedal_position
  99     * percentage
 100     * 10Hz
 101 * parking_brake_status
 102     * boolean, (true == brake engaged)
 103     * 1Hz, but sent immediately on change
 104 * brake_pedal_status
 105     * boolean (True == pedal pressed)
 106     * 1Hz, but sent immediately on change
 107 * transmission_gear_position
 108     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
 109       ninth, tenth, reverse, neutral
 110     * 1Hz, but sent immediately on change
 111 * gear_lever_position
 112     * states: neutral, park, reverse, drive, sport, low, first, second, third,
 113       fourth, fifth, sixth, seventh, eighth, ninth, tenth
 114     * 1Hz, but sent immediately on change
 115 * odometer
 116     * Numerical, km
 117         0 to 16777214.000 km, with about .2m resolution
 118     * 10Hz
 119 * ignition_status
 120     * states: off, accessory, run, start
 121     * 1Hz, but sent immediately on change
 122 * fuel_level
 123     * percentage
 124     * 2Hz
 125 * fuel_consumed_since_restart
 126     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
 127       restarts, like a trip meter)
 128     * 10Hz
 129 * door_status
 130     * Value is State: driver, passenger, rear_left, rear_right.
 131     * Event is boolean: true == ajar
 132     * 1Hz, but sent immediately on change
 133 * headlamp_status
 134     * boolean, true is on
 135     * 1Hz, but sent immediately on change
 136 * high_beam_status
 137     * boolean, true is on
 138     * 1Hz, but sent immediately on change
 139 * windshield_wiper_status
 140     * boolean, true is on
 141     * 1Hz, but sent immediately on change
 142 * latitude
 143     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
 144     * 1Hz
 145 * longitude
 146     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
 147     * 1Hz
 148
 149 ## Signals from Diagnostic Messages
 150
 151 This set of signals is often retreived from OBD-II requests. The units can be
 152 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
 153
 154 * engine_load
 155 * engine_coolant_temperature
 156 * barometric_pressure
 157 * commanded_throttle_position
 158 * throttle_position
 159 * fuel_level
 160 * intake_air_temperature
 161 * intake_manifold_pressure
 162 * running_time
 163 * fuel_pressure
 164 * mass_airflow
 165 * accelerator_pedal_position
 166 * ethanol_fuel_percentage
 167 * engine_oil_temperature
 168 * engine_torque
 169
 170 License
 171 =======
 172
 173 Copyright (c) 2012-2014 Ford Motor Company
 174
 175 Licensed under the BSD license.
 176
 177 [OpenXC]: http://openxcplatform.com