50c166b197c26ce07e2515e0b977eb8da236c8c0
[apps/agl-service-can-low-level.git] / README.md
1 # OpenXC Message Format Specification
2
3 Version: v0.4-dev
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 ## Binary (Protocol Buffers)
11
12 The binary format is encoded using [Google Protocol
13 Buffers](https://code.google.com/p/protobuf/). The format is specified in the
14 file `openxc.proto`. Those are published using the standard length-delimited
15 method (any protobuf library should support this).
16
17 The binary format is best if you need to maximize the amount of data that can be
18 sent from the VI, trading off flexibility for efficiency.
19
20 ## JSON
21
22 This document describes the JSON format and includes a high level description of
23 each type and field. Each JSON message published by a VI is delimited with a
24 `\0 ` character.
25
26 The JSON format is best for most developers, as it is fairly efficient and very
27 flexible.
28
29 ### Extra Values
30
31 Any of the following JSON objects may optionally include an `extras`
32 field. The value may be any valid JSON object or array. The client libraries
33 will do their best to parse this information into a generic format and pass it
34 to your application. For example:
35
36     {"name": "steering_wheel_angle",
37         "value": 45,
38         "extras": {
39             "calibrated": false
40         }
41     }
42
43 ### Single Valued
44
45 There may not be a 1:1 relationship between input and output signals - i.e. raw
46 engine timing CAN signals may be summarized in an "engine performance" metric on
47 the abstract side of the interface.
48
49 The expected format of a single valued message is:
50
51     {"name": "steering_wheel_angle", "value": 45}
52
53 ### Evented
54
55 The expected format of an event message is:
56
57     {"name": "button_event", "value": "up", "event": "pressed"}
58
59 This format is good for something like a button event, where there are two
60 discrete pieces of information in the measurement.
61
62 ### Raw CAN Message format
63
64 The format for a raw CAN message:
65
66     {"bus": 1, "id": 1234, "data": "0x12345678"}
67
68 **bus** - the numerical identifier of the CAN bus where this message originated,
69   most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
70
71 **id** - the CAN message ID
72
73 **data** - up to 8 bytes of data from the CAN message's payload, represented as
74   a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
75   integers, which is why we are not using a numerical data type. Each byte in
76   the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
77   complete string must have an even number of characters.
78
79 ### Diagnostic Messages
80
81 #### Requests
82
83 A diagnostic request is added or cancelled with a JSON object like this example:
84
85     { "command": "diagnostic_request",
86       "action": "add",
87       "request": {
88           "bus": 1,
89           "id": 1234,
90           "mode": 1,
91           "pid": 5,
92           "payload": "0x1234",
93           "multiple_responses": false,
94           "frequency": 1,
95           "name": "my_pid"
96         }
97       }
98     }
99
100 * The `command` must be `diagnostic_request.`
101 * The `action` must be included, and must be one of:
102     * `add` - create a new one-off or recurring diagnostic request.
103     * `cancel` - cancel an existing request.
104 * The details of the request must be included in the `request` field, using
105   the sub-fields defined below.
106
107 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
108 combine to create a unique key to identify a request. These four fields will be
109 referred to as the key of the diagnostic request. For example, to create a
110 simple one-time diagnostic request:
111
112     { "command": "diagnostic_request",
113       "action": "add",
114       "request": {
115           "bus": 1,
116           "id": 1234,
117           "mode": 1,
118           "pid": 5
119         }
120       }
121     }
122
123 Requests are completed after any responses are received (unless
124 `multiple_responses` is set), or the request has timed out after a certain
125 number of seconds. After a request is completed, you can re-`create` the same
126 key to make another request.
127
128 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
129 previous example as a recurring request at 1Hz:
130
131     { "command": "diagnostic_request",
132       "action": "add",
133       "request": {
134           "bus": 1,
135           "id": 1234,
136           "mode": 1,
137           "pid": 5,
138           "frequency": 1
139         }
140       }
141     }
142
143 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
144
145     { "command": "diagnostic_request",
146       "action": "cancel",
147       "request": {
148           "bus": 1,
149           "id": 1234,
150           "mode": 1,
151           "pid": 5
152         }
153       }
154     }
155
156 Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
157 *and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
158 exist in parallel with a recurring request for the same key.
159
160 **bus** - the numerical identifier of the CAN bus where this request should be
161     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
162
163 **id** - the CAN arbitration ID for the request.
164
165 **mode** - the OBD-II mode of the request - 1 through 255 (1 through 9 are the
166     standardized modes and 0x22 is a common proprietary mode).
167
168 **pid** - (optional) the PID for the request, if applicable.
169
170 **payload** - (optional) up to 7 bytes of data for the request's payload
171     represented as a hexadecimal number in a string. Many JSON parser cannot
172     handle 64-bit integers, which is why we are not using a numerical data type.
173     Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
174     is `0x01` - the complete string must have an even number of characters.
175
176 **name** - (optional, defaults to nothing) A human readable, string name for
177   this request. If provided, the response will have a `name` field (much like a
178   normal translated message) with this value in place of `bus`, `id`, `mode` and
179   `pid`.
180
181 **multiple_responses** - (optional, false by default) if true, request will stay
182   active for a full 100ms, even after receiving a diagnostic response message.
183   This is useful for requests to the functional broadcast arbitration ID
184   (`0x7df`) when you need to get responses from multiple modules. It's possible
185   to set this to `true` for non-broadcast requests, but in practice you won't
186   see any additional responses after the first and it will just take up memory
187   in the VI for longer.
188
189 **frequency** - (optional) Make this request a recurring request, at a this
190   frequency in Hz. To send a single non-recurring request, leave this field out.
191
192 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
193 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
194 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
195 OBD-II specification and returned in the `value` field. Set this to `none` to
196 manually override the OBD-II decoding feature for a known PID.
197
198 #### Responses
199
200 The response to a successful request:
201
202     {"bus": 1,
203       "id": 1234,
204       "mode": 1,
205       "pid": 5,
206       "success": true,
207       "payload": "0x1234",
208       "value": 4660}
209
210 and to an unsuccessful request, with the `negative_response_code` and no `pid`
211 echo:
212
213     {"bus": 1,
214       "id": 1234,
215       "mode": 1,
216       "success": false,
217       "negative_response_code": 17}
218
219 **bus** - the numerical identifier of the CAN bus where this response was
220     received.
221
222 **id** - the CAN arbitration ID for this response.
223
224 **mode** - the OBD-II mode of the original diagnostic request.
225
226 **pid** - (optional) the PID for the request, if applicable.
227
228 **success** -  true if the response received was a positive response. If this
229   field is false, the remote node returned an error and the
230   `negative_response_code` field should be populated.
231
232 **negative_response_code** - (optional)  If requested node returned an error,
233     `success` will be `false` and this field will contain the negative response
234     code (NRC).
235
236 Finally, the `payload` and `value` fields are mutually exclusive:
237
238 **payload** - (optional) up to 7 bytes of data returned in the response,
239     represented as a hexadecimal number in a string. Many JSON parser cannot
240     handle 64-bit integers, which is why we are not using a numerical data type.
241
242 **value** - (optional) if the response had a payload, this may be the
243     payload interpreted as an integer.
244
245 The response to a simple PID request would look like this:
246
247     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
248
249 ### Commands
250
251 In addition to the `diagnostic_request` command described earlier, there are
252 other possible values for the `command` field.
253
254 #### Version Query
255
256 The `version` command triggers the VI to inject a firmware version identifier
257 response into the outgoing data stream.
258
259 **Request**
260
261     { "command": "version"}
262
263 **Response**
264
265     { "command_response": "version", "message": "v6.0-dev (default)"}
266
267 #### Device ID Query
268
269 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
270 MAC address of an included Bluetooth module) into into the outgoing data stream.
271
272 **Request**
273
274     { "command": "device_id"}
275
276 **Response**
277
278     { "command_response": "device_id", "message": "0012345678"}
279
280 ### Trace File Format
281
282 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
283 separated by newlines (which may be either `\r\n` or `\n`, depending on the
284 platform the trace file was recorded).
285
286 The first line may be a metadata object, although this is optional:
287
288 ```
289 {"metadata": {
290     "version": "v3.0",
291     "vehicle_interface_id": "7ABF",
292     "vehicle": {
293         "make": "Ford",
294         "model": "Mustang",
295         "trim": "V6 Premium",
296         "year": 2013
297     },
298     "description": "highway drive to work",
299     "driver_name": "TJ Giuli",
300     "vehicle_id": "17N1039247929"
301 }
302 ```
303
304 The following lines are OpenXC messages with a `timestamp` field added, e.g.:
305
306     {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}
307
308 The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
309 (i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).
310
311 ## Official Signals
312
313 These signal names are a part of the OpenXC specification, although some
314 manufacturers may support custom message names.
315
316 * steering_wheel_angle
317     * numerical, -600 to +600 degrees
318     * 10Hz
319 * torque_at_transmission
320     * numerical, -500 to 1500 Nm
321     * 10Hz
322 * engine_speed
323     * numerical, 0 to 16382 RPM
324     * 10Hz
325 * vehicle_speed
326     * numerical, 0 to 655 km/h (this will be positive even if going in reverse
327       as it's not a velocity, although you can use the gear status to figure out
328       direction)
329     * 10Hz
330 * accelerator_pedal_position
331     * percentage
332     * 10Hz
333 * parking_brake_status
334     * boolean, (true == brake engaged)
335     * 1Hz, but sent immediately on change
336 * brake_pedal_status
337     * boolean (True == pedal pressed)
338     * 1Hz, but sent immediately on change
339 * transmission_gear_position
340     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
341       ninth, tenth, reverse, neutral
342     * 1Hz, but sent immediately on change
343 * gear_lever_position
344     * states: neutral, park, reverse, drive, sport, low, first, second, third,
345       fourth, fifth, sixth, seventh, eighth, ninth, tenth
346     * 1Hz, but sent immediately on change
347 * odometer
348     * Numerical, km
349         0 to 16777214.000 km, with about .2m resolution
350     * 10Hz
351 * ignition_status
352     * states: off, accessory, run, start
353     * 1Hz, but sent immediately on change
354 * fuel_level
355     * percentage
356     * 2Hz
357 * fuel_consumed_since_restart
358     * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
359       restarts, like a trip meter)
360     * 10Hz
361 * door_status
362     * Value is State: driver, passenger, rear_left, rear_right.
363     * Event is boolean: true == ajar
364     * 1Hz, but sent immediately on change
365 * headlamp_status
366     * boolean, true is on
367     * 1Hz, but sent immediately on change
368 * high_beam_status
369     * boolean, true is on
370     * 1Hz, but sent immediately on change
371 * windshield_wiper_status
372     * boolean, true is on
373     * 1Hz, but sent immediately on change
374 * latitude
375     * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
376     * 1Hz
377 * longitude
378     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
379     * 1Hz
380
381 ### Signals from Diagnostics Messages
382
383 This set of signals is often retreived from OBD-II requests. The units can be
384 found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
385
386 * engine_load
387 * engine_coolant_temperature
388 * barometric_pressure
389 * commanded_throttle_position
390 * throttle_position
391 * fuel_level
392 * intake_air_temperature
393 * intake_manifold_pressure
394 * running_time
395 * fuel_pressure
396 * mass_airflow
397 * accelerator_pedal_position
398 * ethanol_fuel_percentage
399 * engine_oil_temperature
400 * engine_torque
401
402 License
403 =======
404
405 Copyright (c) 2012-2014 Ford Motor Company
406
407 Licensed under the BSD license.
408
409 [OpenXC]: http://openxcplatform.com