1 # OpenXC Message Format Specification
5 This specification is a part of the [OpenXC platform][OpenXC].
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).
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.
17 The JSON format is best for most developers, as it is fairly efficient and very
20 ## Binary (Protocol Buffers)
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.
27 The binary messages are published by the VI using the standard length-delimited
28 method (any protobuf library should support this).
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.
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
39 For protocol specification visit:
40 https://github.com/msgpack/msgpack/blob/master/spec.md
42 We are using the following lib:
43 https://github.com/camgunz/cmp
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.
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).
54 The first line may be a metadata object, although this is optional:
59 "vehicle_interface_id": "7ABF",
66 "description": "highway drive to work",
67 "driver_name": "TJ Giuli",
68 "vehicle_id": "17N1039247929"
72 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
74 {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
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).
81 These signal names are a part of the OpenXC specification, although some
82 manufacturers may support custom message names.
84 * steering_wheel_angle
85 * numerical, -600 to +600 degrees
87 * torque_at_transmission
88 * numerical, -500 to 1500 Nm
91 * numerical, 0 to 16382 RPM
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
98 * accelerator_pedal_position
101 * parking_brake_status
102 * boolean, (true == brake engaged)
103 * 1Hz, but sent immediately on change
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
117 0 to 16777214.000 km, with about .2m resolution
120 * states: off, accessory, run, start
121 * 1Hz, but sent immediately on change
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)
130 * Value is State: driver, passenger, rear_left, rear_right.
131 * Event is boolean: true == ajar
132 * 1Hz, but sent immediately on change
134 * boolean, true is on
135 * 1Hz, but sent immediately on change
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
143 * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
146 * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
149 ## Signals from Diagnostic Messages
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).
155 * engine_coolant_temperature
156 * barometric_pressure
157 * commanded_throttle_position
160 * intake_air_temperature
161 * intake_manifold_pressure
165 * accelerator_pedal_position
166 * ethanol_fuel_percentage
167 * engine_oil_temperature
173 Copyright (c) 2012-2014 Ford Motor Company
175 Licensed under the BSD license.
177 [OpenXC]: http://openxcplatform.com