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 ## Simple Vehicle Message
  20
  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.
  24
  25 The expected format of a single valued message is:
  26
  27     {"name": "steering_wheel_angle", "value": 45}
  28
  29 ## Evented Simple Vehicle Message
  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 ## CAN Message
  39
  40 The format for a plain 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       "diagnostic_request": {
  69           "bus": 1,
  70           "message_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       "diagnostic_request": {
  96           "bus": 1,
  97           "message_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       "diagnostic_request": {
 115           "bus": 1,
 116           "message_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       "diagnostic_request": {
 129           "bus": 1,
 130           "message_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 **message_id** - the CAN message 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   simple vehicle 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 message 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 Requests to add or cancel a diagnostic request are first acknowledged by the VI,
 183 before any responses to the request are returned. The response uses the standard
 184 command response format:
 185
 186     { "command_response": "diagnostic_request", "status": true}
 187
 188 **status** - true if the request was successfully created or cancelled.
 189
 190 When a node on the network response to the request and the result is published
 191 by the VI, the result looks like:
 192
 193     {"bus": 1,
 194       "message_id": 1234,
 195       "mode": 1,
 196       "pid": 5,
 197       "success": true,
 198       "payload": "0x1234",
 199       "value": 4660}
 200
 201 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 202 echo:
 203
 204     {"bus": 1,
 205       "message_id": 1234,
 206       "mode": 1,
 207       "success": false,
 208       "negative_response_code": 17}
 209
 210 **bus** - the numerical identifier of the CAN bus where this response was
 211     received.
 212
 213 **message_id** - the CAN message ID for this response.
 214
 215 **mode** - the OBD-II mode of the original diagnostic request.
 216
 217 **pid** - (optional) the PID for the request, if applicable.
 218
 219 **success** -  true if the response received was a positive response. If this
 220   field is false, the remote node returned an error and the
 221   `negative_response_code` field should be populated.
 222
 223 **negative_response_code** - (optional)  If requested node returned an error,
 224     `success` will be `false` and this field will contain the negative response
 225     code (NRC).
 226
 227 Finally, the `payload` and `value` fields are mutually exclusive:
 228
 229 **payload** - (optional) up to 7 bytes of data returned in the response,
 230     represented as a hexadecimal number in a string. Many JSON parser cannot
 231     handle 64-bit integers, which is why we are not using a numerical data type.
 232
 233 **value** - (optional) if the response had a payload, this may be the
 234     payload interpreted as an integer.
 235
 236 The response to a simple PID request would look like this:
 237
 238     {"success": true, "bus": 1, "message_id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 239
 240 ## Commands
 241
 242 In addition to the `diagnostic_request` command described earlier, there are
 243 other possible values for the `command` field.
 244
 245 All commands immediately return a `command_response`, e.g.:
 246
 247     { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
 248
 249 **command_response** - an echo of the command this is a ACKing.
 250
 251 **status** - true if the command was understood and performed succesfully.
 252
 253 **message** - (optional) a string message from the VI, e.g. to return a version
 254     descriptor or error message.
 255
 256 ### Version Query
 257
 258 The `version` command triggers the VI to inject a firmware version identifier
 259 response into the outgoing data stream.
 260
 261 **Request**
 262
 263     { "command": "version"}
 264
 265 **Response**
 266
 267     { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
 268
 269 ### Device ID Query
 270
 271 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 272 MAC address of an included Bluetooth module) into into the outgoing data stream.
 273
 274 If no device ID is available, the response message will be "Unknown".
 275
 276 **Request**
 277
 278     { "command": "device_id"}
 279
 280 **Response**
 281
 282     { "command_response": "device_id", "message": "0012345678", "status": true}
 283
 284 ### Passthrough CAN Mode
 285
 286 The `passthrough` command controls whether low-level CAN messages are passed
 287 through from the CAN bus through the VI to the output stream. If the CAN
 288 acceptance filter is in bypass mode and passthrough is enabled, the output
 289 stream will include all received CAN messages. If the bypass filter is enabled,
 290 only those CAN messages that have been pre-defined in the firmware are
 291 forwarded.
 292
 293 **Request**
 294
 295     { "command": "passthrough",
 296       "bus": 1,
 297       "enabled": true
 298     }
 299
 300 **Response**
 301
 302 If the bus in the request was valid and the passthrough mode was changed, the
 303 `status` field in the response will be `true`. If `false`, the passthrough mode
 304 was not changed.
 305
 306     { "command_response": "passthrough", "status": true}
 307
 308 ### Acceptance Filter Bypass
 309
 310 The `af_bypass` command controls whether the CAN message acceptance filter is
 311 bypassed for each CAN controller. By default, hardware acceptance filter (AF) is
 312 enabled in the VI - only previously defined CAN message IDs will be received.
 313 Send this command with `bypass: true` to force the filters to bypassed.
 314
 315 If `passthrough` mode is also enabled, when the AF is bypassed, the output will
 316 include all CAN messages received.
 317
 318 **Request**
 319
 320     { "command": "af_bypass",
 321       "bus": 1,
 322       "bypass": true
 323     }
 324
 325 **Response**
 326
 327 If the bus in the request was valid and the AF mode was changed, the `status`
 328 field in the response will be `true`. If `false`, the passthrough mode was not
 329 changed.
 330
 331     { "command_response": "af_bypass", "status": true}
 332
 333 ### Payload Format Control
 334
 335 The `payload_format` command determines the format for output data from the VI
 336 and the expected format of commands sent to the VI.
 337
 338 Valid formats are `json` and `protobuf`.
 339
 340 **Request**
 341
 342     { "command": "payload_format",
 343       "format": "json"
 344     }
 345
 346 **Response**
 347
 348 If the format was changed successfully, the `status` in the response will be
 349 `true`. The response will be in the original message format, and all subsequent
 350 messages will be in the new format.
 351
 352     { "command_response": "payload_format", "status": true}
 353
 354 ### Automatic Pre-Defined OBD-II PID Requests
 355
 356 The `predefined_obd2` command enables and disables the querying for and
 357 translating of a set of pre-defined OBD-II PIDs from the attached vehicle. When
 358 enabled, the VI will query the vehicle to see if these PIDs are claimed to be
 359 supported and for those that are, it will set up recurring requests. The
 360 responses will be output as simple vehicle messages, with the names defined in
 361 the "Signals Defined from Diagnostic Messages" section below.
 362
 363 **Request**
 364
 365     { "command": "predefined_obd2",
 366       "enabled": true
 367     }
 368
 369 **Response**
 370
 371 If the predefined requests were enabled or disabled successfully, the `status` in
 372 the response will be `true`.
 373
 374     { "command_response": "predefined_obd2", "status": true}
 375
 376 ### C5 Cellular Configuration
 377
 378 The ModemConfigurationCommand message allows users to change certain aspects of modem operation on-the-fly (at runtime). The modem configuration settings are stored in flash memory and are untouched by the bootloader during a software update (assuming the correct cellular_c5 linker file is used during compilation of vi-firmware). Thus, new modem settings persistent across power cycles.
 379
 380 The ModemConfigurationCommand message provides three sub-messages for particular groups of modem settings. These are NetworkOperatorSettings, NetworkDataSettings, and ServerConnectSettings. These configuration messages are described in great detail within the [c5_cellular_config](https://github.com/openxc/vi-firmware/docs/advanced/c5_cell_config.mkd) documentation.
 381
 382 Currently, only the ServerConnectSettings sub-message is supported in the vi-firmware's command interpreter. All other settings are currently compile-time only.
 383
 384 The ServerConnectSettings part of ModemConfigurationCommand allows the user to set the host server name and port that the device will use when opening a TCP socket to upload data. This destination must be running an HTTP server similar to [OpenXCWebServer](https://github.com/openxc/openxc-azure-webserver), which defines a set of supported HTTP transactions where the body is comprised of data in the familiar OpenXC Message Format.
 385
 386 **Request**
 387
 388     { "command": "modem_configuration",
 389       "server": {
 390                 "host": "www.myhost.com",
 391                 "port": 10000
 392           }
 393     }
 394
 395 **Response**
 396
 397         { "command_response": "modem_configuration", "status": true}