README.md

   1 # OpenXC Message Format Specification
   2
   3 This specification is a part of the [OpenXC platform][OpenXC].
   4
   5 An OpenXC vehicle interface sends generic vehicle data over one or more output
   6 interfaces (e.g. USB or Bluetooth) as JSON objects, separated by newlines.
   7
   8 There are two valid message types - single valued and evented.
   9
  10 There may not be a 1:1 relationship between input and output signals - i.e. raw
  11 engine timing CAN signals may be summarized in an "engine performance" metric on
  12 the abstract side of the interface.
  13
  14 ## Single Valued
  15
  16 The expected format of a single valued message is:
  17
  18     {"name": "steering_wheel_angle", "value": 45}
  19
  20 ## Evented
  21
  22 The expected format of an event message is:
  23
  24     {"name": "button_event", "value": "up", "event": "pressed"}
  25
  26 This format is good for something like a button event, where there are two
  27 discrete pieces of information in the measurement.
  28
  29 ## Official Signals
  30
  31 These signal names are a part of the OpenXC specification, although some
  32 manufacturers may support custom message names.
  33
  34 * steering_wheel_angle
  35     * numerical, -600 to +600 degrees
  36     * 10Hz
  37 * torque_at_transmission
  38     * numerical, -500 to 1500 Nm
  39     * 10Hz
  40 * engine_speed
  41     * numerical, 0 to 16382 RPM
  42     * 10Hz
  43 * vehicle_speed
  44     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
  45       as it's not a velocity, although you can use the gear status to figure out
  46       direction)
  47     * 10Hz
  48 * accelerator_pedal_position
  49     * percentage
  50     * 10Hz
  51 * parking_brake_status
  52     * boolean, (true == brake engaged)
  53     * 1Hz, but sent immediately on change
  54 * brake_pedal_status
  55     * boolean (True == pedal pressed)
  56     * 1Hz, but sent immediately on change
  57 * transmission_gear_position
  58     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
  59       reverse, neutral
  60     * 1Hz, but sent immediately on change
  61 * gear_lever_position
  62     * states: neutral, park, reverse, drive, sport, low, first, second, third,
  63       fourth, fifth, sixth
  64 * odometer
  65     * Numerical, km
  66         0 to 16777214.000 km, with about .2m resolution
  67     * 10Hz
  68 * ignition_status
  69     * states: off, accessory, run, start
  70     * 1Hz, but sent immediately on change
  71 * fuel_level
  72     * percentage
  73     * 2Hz
  74 * fuel_consumed_since_restart
  75     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
  76       restarts, like a trip meter)
  77     * 10Hz
  78 * door_status
  79     * Value is State: driver, passenger, rear_left, rear_right.
  80     * Event is boolean: true == ajar
  81     * 1Hz, but sent immediately on change
  82 * headlamp_status
  83     * boolean, true is on
  84     * 1Hz, but sent immediately on change
  85 * high_beam_status
  86     * boolean, true is on
  87     * 1Hz, but sent immediately on change
  88 * windshield_wiper_status
  89     * boolean, true is on
  90     * 1Hz, but sent immediately on change
  91 * latitude
  92     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
  93     * 1Hz
  94 * longitude
  95     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
  96     * 1Hz
  97
  98 ## Raw CAN Message format
  99
 100 An OpenXC vehicle interface may also output raw CAN messages. Each CAN message
 101 is sent as a JSON object, separated by newlines. The format of each object is:
 102
 103     {"bus": 1, "id": 1234, "value": "0x12345678"}
 104
 105 **bus** - the numerical identifier of the CAN bus where this message originated,
 106   most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
 107
 108 **id** - the CAN message ID
 109
 110 **data** - up to 8 bytes of data from the CAN message's payload, represented as
 111   a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
 112   integers, which is why we are not using a numerical data type.
 113
 114 License
 115 =======
 116
 117 Copyright (c) 2012-2013 Ford Motor Company
 118
 119 Licensed under the BSD license.
 120
 121 [OpenXC]: http://openxcplatform.com