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 ## Trace File Format
  43
  44 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
  45 separated by newlines (which may be either `\r\n` or `\n`, depending on the
  46 platform the trace file was recorded).
  47
  48 The first line may be a metadata object, although this is optional:
  49
  50 ```
  51 {"metadata": {
  52     "version": "v3.0",
  53     "vehicle_interface_id": "7ABF",
  54     "vehicle": {
  55         "make": "Ford",
  56         "model": "Mustang",
  57         "trim": "V6 Premium",
  58         "year": 2013
  59     },
  60     "description": "highway drive to work",
  61     "driver_name": "TJ Giuli",
  62     "vehicle_id": "17N1039247929"
  63 }
  64 ```
  65
  66 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
  67
  68     {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
  69
  70 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
  71 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
  72
  73 ## Official Signals
  74
  75 These signal names are a part of the OpenXC specification, although some
  76 manufacturers may support custom message names.
  77
  78 * steering_wheel_angle
  79     * numerical, -600 to +600 degrees
  80     * 10Hz
  81 * torque_at_transmission
  82     * numerical, -500 to 1500 Nm
  83     * 10Hz
  84 * engine_speed
  85     * numerical, 0 to 16382 RPM
  86     * 10Hz
  87 * vehicle_speed
  88     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
  89       as it's not a velocity, although you can use the gear status to figure out
  90       direction)
  91     * 10Hz
  92 * accelerator_pedal_position
  93     * percentage
  94     * 10Hz
  95 * parking_brake_status
  96     * boolean, (true == brake engaged)
  97     * 1Hz, but sent immediately on change
  98 * brake_pedal_status
  99     * boolean (True == pedal pressed)
 100     * 1Hz, but sent immediately on change
 101 * transmission_gear_position
 102     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
 103       ninth, tenth, reverse, neutral
 104     * 1Hz, but sent immediately on change
 105 * gear_lever_position
 106     * states: neutral, park, reverse, drive, sport, low, first, second, third,
 107       fourth, fifth, sixth, seventh, eighth, ninth, tenth
 108     * 1Hz, but sent immediately on change
 109 * odometer
 110     * Numerical, km
 111         0 to 16777214.000 km, with about .2m resolution
 112     * 10Hz
 113 * ignition_status
 114     * states: off, accessory, run, start
 115     * 1Hz, but sent immediately on change
 116 * fuel_level
 117     * percentage
 118     * 2Hz
 119 * fuel_consumed_since_restart
 120     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
 121       restarts, like a trip meter)
 122     * 10Hz
 123 * door_status
 124     * Value is State: driver, passenger, rear_left, rear_right.
 125     * Event is boolean: true == ajar
 126     * 1Hz, but sent immediately on change
 127 * headlamp_status
 128     * boolean, true is on
 129     * 1Hz, but sent immediately on change
 130 * high_beam_status
 131     * boolean, true is on
 132     * 1Hz, but sent immediately on change
 133 * windshield_wiper_status
 134     * boolean, true is on
 135     * 1Hz, but sent immediately on change
 136 * latitude
 137     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
 138     * 1Hz
 139 * longitude
 140     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
 141     * 1Hz
 142
 143 ## Signals from Diagnostic Messages
 144
 145 This set of signals is often retreived from OBD-II requests. The units can be
 146 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
 147
 148 * engine_load
 149 * engine_coolant_temperature
 150 * barometric_pressure
 151 * commanded_throttle_position
 152 * throttle_position
 153 * fuel_level
 154 * intake_air_temperature
 155 * intake_manifold_pressure
 156 * running_time
 157 * fuel_pressure
 158 * mass_airflow
 159 * accelerator_pedal_position
 160 * ethanol_fuel_percentage
 161 * engine_oil_temperature
 162 * engine_torque
 163
 164 License
 165 =======
 166
 167 Copyright (c) 2012-2014 Ford Motor Company
 168
 169 Licensed under the BSD license.
 170
 171 [OpenXC]: http://openxcplatform.com