README.md

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