JSON.mkd

   1 # OpenXC JSON Message Format
   2
   3 Each JSON message published by a VI is delimited with a `\0 ` character.
   4
   5 ## Extra Values
   6
   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:
  11
  12     {"name": "steering_wheel_angle",
  13         "value": 45,
  14         "extras": {
  15             "calibrated": false
  16         }
  17     }
  18
  19 ## Single Valued
  20
  21 There may not be a 1:1 relationship between input and output signals - i.e. raw
  22 engine timing CAN signals may be summarized in an "engine performance" metric on
  23 the abstract side of the interface.
  24
  25 The expected format of a single valued message is:
  26
  27     {"name": "steering_wheel_angle", "value": 45}
  28
  29 ## Evented
  30
  31 The expected format of an event message is:
  32
  33     {"name": "button_event", "value": "up", "event": "pressed"}
  34
  35 This format is good for something like a button event, where there are two
  36 discrete pieces of information in the measurement.
  37
  38 ## Raw CAN Message format
  39
  40 The format for a raw CAN message:
  41
  42     {"bus": 1, "id": 1234, "data": "0x12345678"}
  43
  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).
  46
  47 **id** - the CAN message ID
  48
  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
  54   optional.
  55
  56 ## Diagnostic Messages
  57
  58 ### Requests
  59
  60 A diagnostic request is added or cancelled with a JSON object like this example:
  61
  62     { "command": "diagnostic_request",
  63       "action": "add",
  64       "request": {
  65           "bus": 1,
  66           "id": 1234,
  67           "mode": 1,
  68           "pid": 5,
  69           "payload": "0x1234",
  70           "multiple_responses": false,
  71           "frequency": 1,
  72           "name": "my_pid"
  73         }
  74       }
  75     }
  76
  77 * The `command` must be `diagnostic_request.`
  78 * The `action` must be included, and must be one of:
  79     * `add` - create a new one-off or recurring diagnostic request.
  80     * `cancel` - cancel an existing request.
  81 * The details of the request must be included in the `request` field, using
  82   the sub-fields defined below.
  83
  84 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
  85 combine to create a unique key to identify a request. These four fields will be
  86 referred to as the key of the diagnostic request. For example, to create a
  87 simple one-time diagnostic request:
  88
  89     { "command": "diagnostic_request",
  90       "action": "add",
  91       "request": {
  92           "bus": 1,
  93           "id": 1234,
  94           "mode": 1,
  95           "pid": 5
  96         }
  97       }
  98     }
  99
 100 Requests are completed after any responses are received (unless
 101 `multiple_responses` is set), or the request has timed out after a certain
 102 number of seconds. After a request is completed, you can re-`create` the same
 103 key to make another request.
 104
 105 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
 106 previous example as a recurring request at 1Hz:
 107
 108     { "command": "diagnostic_request",
 109       "action": "add",
 110       "request": {
 111           "bus": 1,
 112           "id": 1234,
 113           "mode": 1,
 114           "pid": 5,
 115           "frequency": 1
 116         }
 117       }
 118     }
 119
 120 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
 121
 122     { "command": "diagnostic_request",
 123       "action": "cancel",
 124       "request": {
 125           "bus": 1,
 126           "id": 1234,
 127           "mode": 1,
 128           "pid": 5
 129         }
 130       }
 131     }
 132
 133 Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
 134 *and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
 135 exist in parallel with a recurring request for the same key.
 136
 137 **bus** - the numerical identifier of the CAN bus where this request should be
 138     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
 139
 140 **id** - the CAN arbitration ID for the request.
 141
 142 **mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
 143     standardized modes and 0x22 is a common proprietary mode).
 144
 145 **pid** - (optional) the PID for the request, if applicable.
 146
 147 **payload** - (optional) up to 7 bytes of data for the request's payload
 148     represented as a hexadecimal number in a string. Many JSON parser cannot
 149     handle 64-bit integers, which is why we are not using a numerical data type.
 150     Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
 151     is `0x01` - the complete string must have an even number of characters. The
 152     `0x` prefix is optional.
 153
 154 **name** - (optional, defaults to nothing) A human readable, string name for
 155   this request. If provided, the response will have a `name` field (much like a
 156   normal translated message) with this value in place of `bus`, `id`, `mode` and
 157   `pid`.
 158
 159 **multiple_responses** - (optional, false by default) if true, request will stay
 160   active for a full 100ms, even after receiving a diagnostic response message.
 161   This is useful for requests to the functional broadcast arbitration ID
 162   (`0x7df`) when you need to get responses from multiple modules. It's possible
 163   to set this to `true` for non-broadcast requests, but in practice you won't
 164   see any additional responses after the first and it will just take up memory
 165   in the VI for longer.
 166
 167 **frequency** - (optional) Make this request a recurring request, at a this
 168   frequency in Hz. To send a single non-recurring request, leave this field out.
 169
 170 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
 171 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
 172 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
 173 OBD-II specification and returned in the `value` field. Set this to `none` to
 174 manually override the OBD-II decoding feature for a known PID.
 175
 176 ### Responses
 177
 178 The response to a successful request:
 179
 180     {"bus": 1,
 181       "id": 1234,
 182       "mode": 1,
 183       "pid": 5,
 184       "success": true,
 185       "payload": "0x1234",
 186       "value": 4660}
 187
 188 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 189 echo:
 190
 191     {"bus": 1,
 192       "id": 1234,
 193       "mode": 1,
 194       "success": false,
 195       "negative_response_code": 17}
 196
 197 **bus** - the numerical identifier of the CAN bus where this response was
 198     received.
 199
 200 **id** - the CAN arbitration ID for this response.
 201
 202 **mode** - the OBD-II mode of the original diagnostic request.
 203
 204 **pid** - (optional) the PID for the request, if applicable.
 205
 206 **success** -  true if the response received was a positive response. If this
 207   field is false, the remote node returned an error and the
 208   `negative_response_code` field should be populated.
 209
 210 **negative_response_code** - (optional)  If requested node returned an error,
 211     `success` will be `false` and this field will contain the negative response
 212     code (NRC).
 213
 214 Finally, the `payload` and `value` fields are mutually exclusive:
 215
 216 **payload** - (optional) up to 7 bytes of data returned in the response,
 217     represented as a hexadecimal number in a string. Many JSON parser cannot
 218     handle 64-bit integers, which is why we are not using a numerical data type.
 219
 220 **value** - (optional) if the response had a payload, this may be the
 221     payload interpreted as an integer.
 222
 223 The response to a simple PID request would look like this:
 224
 225     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 226
 227 ## Commands
 228
 229 In addition to the `diagnostic_request` command described earlier, there are
 230 other possible values for the `command` field.
 231
 232 ### Version Query
 233
 234 The `version` command triggers the VI to inject a firmware version identifier
 235 response into the outgoing data stream.
 236
 237 **Request**
 238
 239     { "command": "version"}
 240
 241 **Response**
 242
 243     { "command_response": "version", "message": "v6.0-dev (default)"}
 244
 245 ### Device ID Query
 246
 247 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 248 MAC address of an included Bluetooth module) into into the outgoing data stream.
 249
 250 **Request**
 251
 252     { "command": "device_id"}
 253
 254 **Response**
 255
 256     { "command_response": "device_id", "message": "0012345678"}
 257
 258 ### Passthrough CAN Mode
 259
 260 The `passthrough` command controls whether low-level CAN messages are passed
 261 through from the CAN bus through the VI to the output stream. If the CAN
 262 acceptance filter is in bypass mode and passthrough is enabled, the output
 263 stream will include all received CAN messages. If the bypass filter is enabled,
 264 only those CAN messages that have been pre-defined in the firmware are
 265 forwarded.
 266
 267 **Request**
 268
 269     { "command": "passthrough",
 270       "bus": 1,
 271       "enabled": true
 272     }
 273
 274 **Response**
 275
 276 If the bus in the request was valid and the passthrough mode was changed, the
 277 `status` field in the response will be `true`. If `false`, the passthrough mode
 278 was not changed.
 279
 280     { "command_response": "passthrough", "status": true}
 281
 282 ### Acceptance Filter Bypass
 283
 284 The `af_bypass` command controls whether the CAN message acceptance filter is
 285 bypassed for each CAN controller. By default, hardware acceptance filter (AF) is
 286 enabled in the VI - only previously defined CAN message IDs will be received.
 287 Send this command with `bypass: true` to force the filters to bypassed.
 288
 289 If `passthrough` mode is also enabled, when the AF is bypassed, the output will
 290 include all CAN messages received.
 291
 292 **Request**
 293
 294     { "command": "af_bypass",
 295       "bus": 1,
 296       "bypass": true
 297     }
 298
 299 **Response**
 300
 301 If the bus in the request was valid and the AF mode was changed, the `status`
 302 field in the response will be `true`. If `false`, the passthrough mode was not
 303 changed.
 304
 305     { "command_response": "af_bypass", "status": true}
 306
 307 ### Payload Format Control
 308
 309 The `payload_format` command determines the format for output data from the VI
 310 and the expected format of commands sent to the VI.
 311
 312 Valid formats are `json` and `protobuf`.
 313
 314 **Request**
 315
 316     { "command": "payload_format",
 317       "format": "json"
 318     }
 319
 320 **Response**
 321
 322 If the format was changed successfully, the `status` in the response will be
 323 `true`. The response will be in the original message format, and all subsequent
 324 messages will be in the new format.
 325
 326     { "command_response": "payload_format", "status": true}
 327
 328 ### Automatic Pre-Defined OBD-II PID Requests
 329
 330 The `predefined_obd2` command enables and disables the querying for and
 331 translating of a set of pre-defined OBD-II PIDs from the attached vehicle. When
 332 enabled, the VI will query the vehicle to see if these PIDs are claimed to be
 333 supported and for those that are, it will set up recurring requests. The
 334 responses will be output as simple vehicle messages, with the names defined in
 335 the "Signals Defined from Diagnostic Messages" section below.
 336
 337 **Request**
 338
 339     { "command": "predefined_obd2",
 340       "enabled": true
 341     }
 342
 343 **Response**
 344
 345 f the predefined requests were enabled or disabled successfully, the `status` in
 346 the response will be `true`.
 347
 348     { "command_response": "predefined_obd2", "status": true}
 349