1 # OpenXC JSON Message Format
3 Each JSON message published by a VI is delimited with a `\0 ` character.
7 Any of the following JSON objects may optionally include an `extras`
8 field. The value may be any valid JSON object or array. The client libraries
9 will do their best to parse this information into a generic format and pass it
10 to your application. For example:
12 {"name": "steering_wheel_angle",
19 ## Simple Vehicle Message
21 There may not be a 1:1 relationship between input and output signals - i.e.
22 engine timing CAN signals may be summarized in an "engine performance" metric on
23 the abstract side of the interface.
25 The expected format of a single valued message is:
27 {"name": "steering_wheel_angle", "value": 45}
29 ## Evented Simple Vehicle Message
31 The expected format of an event message is:
33 {"name": "button_event", "value": "up", "event": "pressed"}
35 This format is good for something like a button event, where there are two
36 discrete pieces of information in the measurement.
40 The format for a plain CAN message:
42 {"bus": 1, "id": 1234, "data": "0x12345678"}
44 **bus** - the numerical identifier of the CAN bus where this message originated,
45 most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
47 **id** - the CAN message ID
49 **data** - up to 8 bytes of data from the CAN message's payload, represented as
50 a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
51 integers, which is why we are not using a numerical data type. Each byte in
52 the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
53 complete string must have an even number of characters. The `0x` prefix is
56 **format** - (optional) explicitly set the frame format for the CAN message, one
57 of `standard` or `extended`. If the `id` is greater than `0x7ff`, the extended
58 frame format will be selected automatically.
60 ## Diagnostic Messages
64 A diagnostic request is added or cancelled with a JSON object like this example:
66 { "command": "diagnostic_request",
74 "multiple_responses": false,
81 * The `command` must be `diagnostic_request.`
82 * The `action` must be included, and must be one of:
83 * `add` - create a new one-off or recurring diagnostic request.
84 * `cancel` - cancel an existing request.
85 * The details of the request must be included in the `request` field, using
86 the sub-fields defined below.
88 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
89 combine to create a unique key to identify a request. These four fields will be
90 referred to as the key of the diagnostic request. For example, to create a
91 simple one-time diagnostic request:
93 { "command": "diagnostic_request",
104 Requests are completed after any responses are received (unless
105 `multiple_responses` is set), or the request has timed out after a certain
106 number of seconds. After a request is completed, you can re-`create` the same
107 key to make another request.
109 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
110 previous example as a recurring request at 1Hz:
112 { "command": "diagnostic_request",
124 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
126 { "command": "diagnostic_request",
137 Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
138 *and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
139 exist in parallel with a recurring request for the same key.
141 **bus** - the numerical identifier of the CAN bus where this request should be
142 sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
144 **id** - the CAN arbitration ID for the request.
146 **mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
147 standardized modes and 0x22 is a common proprietary mode).
149 **pid** - (optional) the PID for the request, if applicable.
151 **payload** - (optional) up to 7 bytes of data for the request's payload
152 represented as a hexadecimal number in a string. Many JSON parser cannot
153 handle 64-bit integers, which is why we are not using a numerical data type.
154 Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
155 is `0x01` - the complete string must have an even number of characters. The
156 `0x` prefix is optional.
158 **name** - (optional, defaults to nothing) A human readable, string name for
159 this request. If provided, the response will have a `name` field (much like a
160 simple vehicle message) with this value in place of `bus`, `id`, `mode` and
163 **multiple_responses** - (optional, false by default) if true, request will stay
164 active for a full 100ms, even after receiving a diagnostic response message.
165 This is useful for requests to the functional broadcast arbitration ID
166 (`0x7df`) when you need to get responses from multiple modules. It's possible
167 to set this to `true` for non-broadcast requests, but in practice you won't
168 see any additional responses after the first and it will just take up memory
169 in the VI for longer.
171 **frequency** - (optional) Make this request a recurring request, at a this
172 frequency in Hz. To send a single non-recurring request, leave this field out.
174 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
175 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
176 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
177 OBD-II specification and returned in the `value` field. Set this to `none` to
178 manually override the OBD-II decoding feature for a known PID.
182 The response to a successful request:
192 and to an unsuccessful request, with the `negative_response_code` and no `pid`
199 "negative_response_code": 17}
201 **bus** - the numerical identifier of the CAN bus where this response was
204 **id** - the CAN arbitration ID for this response.
206 **mode** - the OBD-II mode of the original diagnostic request.
208 **pid** - (optional) the PID for the request, if applicable.
210 **success** - true if the response received was a positive response. If this
211 field is false, the remote node returned an error and the
212 `negative_response_code` field should be populated.
214 **negative_response_code** - (optional) If requested node returned an error,
215 `success` will be `false` and this field will contain the negative response
218 Finally, the `payload` and `value` fields are mutually exclusive:
220 **payload** - (optional) up to 7 bytes of data returned in the response,
221 represented as a hexadecimal number in a string. Many JSON parser cannot
222 handle 64-bit integers, which is why we are not using a numerical data type.
224 **value** - (optional) if the response had a payload, this may be the
225 payload interpreted as an integer.
227 The response to a simple PID request would look like this:
229 {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
233 In addition to the `diagnostic_request` command described earlier, there are
234 other possible values for the `command` field.
238 The `version` command triggers the VI to inject a firmware version identifier
239 response into the outgoing data stream.
243 { "command": "version"}
247 { "command_response": "version", "message": "v6.0-dev (default)"}
251 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
252 MAC address of an included Bluetooth module) into into the outgoing data stream.
256 { "command": "device_id"}
260 { "command_response": "device_id", "message": "0012345678"}
262 ### Passthrough CAN Mode
264 The `passthrough` command controls whether low-level CAN messages are passed
265 through from the CAN bus through the VI to the output stream. If the CAN
266 acceptance filter is in bypass mode and passthrough is enabled, the output
267 stream will include all received CAN messages. If the bypass filter is enabled,
268 only those CAN messages that have been pre-defined in the firmware are
273 { "command": "passthrough",
280 If the bus in the request was valid and the passthrough mode was changed, the
281 `status` field in the response will be `true`. If `false`, the passthrough mode
284 { "command_response": "passthrough", "status": true}
286 ### Acceptance Filter Bypass
288 The `af_bypass` command controls whether the CAN message acceptance filter is
289 bypassed for each CAN controller. By default, hardware acceptance filter (AF) is
290 enabled in the VI - only previously defined CAN message IDs will be received.
291 Send this command with `bypass: true` to force the filters to bypassed.
293 If `passthrough` mode is also enabled, when the AF is bypassed, the output will
294 include all CAN messages received.
298 { "command": "af_bypass",
305 If the bus in the request was valid and the AF mode was changed, the `status`
306 field in the response will be `true`. If `false`, the passthrough mode was not
309 { "command_response": "af_bypass", "status": true}
311 ### Payload Format Control
313 The `payload_format` command determines the format for output data from the VI
314 and the expected format of commands sent to the VI.
316 Valid formats are `json` and `protobuf`.
320 { "command": "payload_format",
326 If the format was changed successfully, the `status` in the response will be
327 `true`. The response will be in the original message format, and all subsequent
328 messages will be in the new format.
330 { "command_response": "payload_format", "status": true}
332 ### Automatic Pre-Defined OBD-II PID Requests
334 The `predefined_obd2` command enables and disables the querying for and
335 translating of a set of pre-defined OBD-II PIDs from the attached vehicle. When
336 enabled, the VI will query the vehicle to see if these PIDs are claimed to be
337 supported and for those that are, it will set up recurring requests. The
338 responses will be output as simple vehicle messages, with the names defined in
339 the "Signals Defined from Diagnostic Messages" section below.
343 { "command": "predefined_obd2",
349 f the predefined requests were enabled or disabled successfully, the `status` in
350 the response will be `true`.
352 { "command_response": "predefined_obd2", "status": true}