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 **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.
  59
  60 ## Diagnostic Messages
  61
  62 ### Requests
  63
  64 A diagnostic request is added or cancelled with a JSON object like this example:
  65
  66     { "command": "diagnostic_request",
  67       "action": "add",
  68       "request": {
  69           "bus": 1,
  70           "id": 1234,
  71           "mode": 1,
  72           "pid": 5,
  73           "payload": "0x1234",
  74           "multiple_responses": false,
  75           "frequency": 1,
  76           "name": "my_pid"
  77         }
  78       }
  79     }
  80
  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.
  87
  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:
  92
  93     { "command": "diagnostic_request",
  94       "action": "add",
  95       "request": {
  96           "bus": 1,
  97           "id": 1234,
  98           "mode": 1,
  99           "pid": 5
 100         }
 101       }
 102     }
 103
 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.
 108
 109 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
 110 previous example as a recurring request at 1Hz:
 111
 112     { "command": "diagnostic_request",
 113       "action": "add",
 114       "request": {
 115           "bus": 1,
 116           "id": 1234,
 117           "mode": 1,
 118           "pid": 5,
 119           "frequency": 1
 120         }
 121       }
 122     }
 123
 124 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
 125
 126     { "command": "diagnostic_request",
 127       "action": "cancel",
 128       "request": {
 129           "bus": 1,
 130           "id": 1234,
 131           "mode": 1,
 132           "pid": 5
 133         }
 134       }
 135     }
 136
 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.
 140
 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).
 143
 144 **id** - the CAN arbitration ID for the request.
 145
 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).
 148
 149 **pid** - (optional) the PID for the request, if applicable.
 150
 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.
 157
 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   normal translated message) with this value in place of `bus`, `id`, `mode` and
 161   `pid`.
 162
 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.
 170
 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.
 173
 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.
 179
 180 ### Responses
 181
 182 The response to a successful request:
 183
 184     {"bus": 1,
 185       "id": 1234,
 186       "mode": 1,
 187       "pid": 5,
 188       "success": true,
 189       "payload": "0x1234",
 190       "value": 4660}
 191
 192 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 193 echo:
 194
 195     {"bus": 1,
 196       "id": 1234,
 197       "mode": 1,
 198       "success": false,
 199       "negative_response_code": 17}
 200
 201 **bus** - the numerical identifier of the CAN bus where this response was
 202     received.
 203
 204 **id** - the CAN arbitration ID for this response.
 205
 206 **mode** - the OBD-II mode of the original diagnostic request.
 207
 208 **pid** - (optional) the PID for the request, if applicable.
 209
 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.
 213
 214 **negative_response_code** - (optional)  If requested node returned an error,
 215     `success` will be `false` and this field will contain the negative response
 216     code (NRC).
 217
 218 Finally, the `payload` and `value` fields are mutually exclusive:
 219
 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.
 223
 224 **value** - (optional) if the response had a payload, this may be the
 225     payload interpreted as an integer.
 226
 227 The response to a simple PID request would look like this:
 228
 229     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 230
 231 ## Commands
 232
 233 In addition to the `diagnostic_request` command described earlier, there are
 234 other possible values for the `command` field.
 235
 236 ### Version Query
 237
 238 The `version` command triggers the VI to inject a firmware version identifier
 239 response into the outgoing data stream.
 240
 241 **Request**
 242
 243     { "command": "version"}
 244
 245 **Response**
 246
 247     { "command_response": "version", "message": "v6.0-dev (default)"}
 248
 249 ### Device ID Query
 250
 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.
 253
 254 **Request**
 255
 256     { "command": "device_id"}
 257
 258 **Response**
 259
 260     { "command_response": "device_id", "message": "0012345678"}
 261
 262 ### Passthrough CAN Mode
 263
 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
 269 forwarded.
 270
 271 **Request**
 272
 273     { "command": "passthrough",
 274       "bus": 1,
 275       "enabled": true
 276     }
 277
 278 **Response**
 279
 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
 282 was not changed.
 283
 284     { "command_response": "passthrough", "status": true}
 285
 286 ### Acceptance Filter Bypass
 287
 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.
 292
 293 If `passthrough` mode is also enabled, when the AF is bypassed, the output will
 294 include all CAN messages received.
 295
 296 **Request**
 297
 298     { "command": "af_bypass",
 299       "bus": 1,
 300       "bypass": true
 301     }
 302
 303 **Response**
 304
 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
 307 changed.
 308
 309     { "command_response": "af_bypass", "status": true}
 310
 311 ### Payload Format Control
 312
 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.
 315
 316 Valid formats are `json` and `protobuf`.
 317
 318 **Request**
 319
 320     { "command": "payload_format",
 321       "format": "json"
 322     }
 323
 324 **Response**
 325
 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.
 329
 330     { "command_response": "payload_format", "status": true}
 331
 332 ### Automatic Pre-Defined OBD-II PID Requests
 333
 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.
 340
 341 **Request**
 342
 343     { "command": "predefined_obd2",
 344       "enabled": true
 345     }
 346
 347 **Response**
 348
 349 f the predefined requests were enabled or disabled successfully, the `status` in
 350 the response will be `true`.
 351
 352     { "command_response": "predefined_obd2", "status": true}
 353