README.md

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