JSON.mkd

   1 # OpenXC JSON Message Format
   2
   3 Each JSON message published by a VI is delimited with a `\0 ` character.
   4
   5 ## Table of Contents
   6 1. [Vehicle Messages](#vehicle-messages)
   7 2. [CAN Message](#can-message)
   8 3. [Diagnostic Message](#diagnostic-message)
   9 4. [Commands](#commands)
  10 5. [Extra Values](#extra-values)
  11
  12 ## Vehicle Messages
  13
  14 ### Simple Vehicle Message
  15
  16 There may not be a 1:1 relationship between input and output signals - i.e.
  17 engine timing CAN signals may be summarized in an "engine performance" metric on
  18 the abstract side of the interface.
  19
  20 The expected format of a single valued message is:
  21
  22     {"name": "steering_wheel_angle", "value": 45}
  23
  24 ### Evented Simple Vehicle Message
  25
  26 The expected format of an event message is:
  27
  28     {"name": "button_event", "value": "up", "event": "pressed"}
  29
  30 This format is good for something like a button event, where there are two
  31 discrete pieces of information in the measurement.
  32
  33 ## CAN Message
  34
  35 The format for a plain CAN message:
  36
  37     {"bus": 1, "id": 1234, "data": "0x12345678"}
  38
  39 **bus** - the numerical identifier of the CAN bus where this message originated,
  40   most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
  41
  42 **id** - the CAN message ID
  43
  44 **data** - up to 8 bytes of data from the CAN message's payload, represented as
  45   a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
  46   integers, which is why we are not using a numerical data type. Each byte in
  47   the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
  48   complete string must have an even number of characters. The `0x` prefix is
  49   optional.
  50
  51 **format** - (optional) explicitly set the frame format for the CAN message, one
  52   of `standard` or `extended`. If the `id` is greater than `0x7ff`, the extended
  53   frame format will be selected automatically.
  54
  55 ## Diagnostic Message
  56
  57 ### Requests
  58
  59 A diagnostic request is added or cancelled with a JSON object like this example:
  60
  61     { "command": "diagnostic_request",
  62       "action": "add",
  63       "diagnostic_request": {
  64           "bus": 1,
  65           "message_id": 1234,
  66           "mode": 1,
  67           "pid": 5,
  68           "payload": "0x1234",
  69           "multiple_responses": false,
  70           "frequency": 1,
  71           "name": "my_pid"
  72         }
  73       }
  74     }
  75
  76 * The `command` must be `diagnostic_request.`
  77 * The `action` must be included, and must be one of:
  78     * `add` - create a new one-off or recurring diagnostic request.
  79     * `cancel` - cancel an existing request.
  80 * The details of the request must be included in the `request` field, using
  81   the sub-fields defined below.
  82
  83 A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
  84 combine to create a unique key to identify a request. These four fields will be
  85 referred to as the key of the diagnostic request. For example, to create a
  86 simple one-time diagnostic request:
  87
  88     { "command": "diagnostic_request",
  89       "action": "add",
  90       "diagnostic_request": {
  91           "bus": 1,
  92           "message_id": 1234,
  93           "mode": 1,
  94           "pid": 5
  95         }
  96       }
  97     }
  98
  99 Requests are completed after any responses are received (unless
 100 `multiple_responses` is set), or the request has timed out after a certain
 101 number of seconds. After a request is completed, you can re-`create` the same
 102 key to make another request.
 103
 104 Requests with a `frequency` are added as *recurring* requests, e.g. to add the
 105 previous example as a recurring request at 1Hz:
 106
 107     { "command": "diagnostic_request",
 108       "action": "add",
 109       "diagnostic_request": {
 110           "bus": 1,
 111           "message_id": 1234,
 112           "mode": 1,
 113           "pid": 5,
 114           "frequency": 1
 115         }
 116       }
 117     }
 118
 119 To cancel a recurring request, send a `cancel` action with the same key, e.g.:
 120
 121     { "command": "diagnostic_request",
 122       "action": "cancel",
 123       "diagnostic_request": {
 124           "bus": 1,
 125           "message_id": 1234,
 126           "mode": 1,
 127           "pid": 5
 128         }
 129       }
 130     }
 131
 132 Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
 133 *and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
 134 exist in parallel with a recurring request for the same key.
 135
 136 **bus** - the numerical identifier of the CAN bus where this request should be
 137     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
 138
 139 **message_id** - the CAN message ID for the request.
 140
 141 **mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
 142     standardized modes and 0x22 is a common proprietary mode).
 143
 144 **pid** - (optional) the PID for the request, if applicable.
 145
 146 **payload** - (optional) up to 7 bytes of data for the request's payload
 147     represented as a hexadecimal number in a string. Many JSON parser cannot
 148     handle 64-bit integers, which is why we are not using a numerical data type.
 149     Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
 150     is `0x01` - the complete string must have an even number of characters. The
 151     `0x` prefix is optional.
 152
 153 **name** - (optional, defaults to nothing) A human readable, string name for
 154   this request. If provided, the response will have a `name` field (much like a
 155   simple vehicle message) with this value in place of `bus`, `id`, `mode` and
 156   `pid`.
 157
 158 **multiple_responses** - (optional, false by default) if true, request will stay
 159   active for a full 100ms, even after receiving a diagnostic response message.
 160   This is useful for requests to the functional broadcast message ID
 161   (`0x7df`) when you need to get responses from multiple modules. It's possible
 162   to set this to `true` for non-broadcast requests, but in practice you won't
 163   see any additional responses after the first and it will just take up memory
 164   in the VI for longer.
 165
 166 **frequency** - (optional) Make this request a recurring request, at a this
 167   frequency in Hz. To send a single non-recurring request, leave this field out.
 168
 169 **decoded_type** - (optional, defaults to "obd2" if the request is a recognized
 170 OBD-II mode 1 request, otherwise "none") If specified, the valid values are
 171 `"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
 172 OBD-II specification and returned in the `value` field. Set this to `none` to
 173 manually override the OBD-II decoding feature for a known PID.
 174
 175 ### Responses
 176
 177 Requests to add or cancel a diagnostic request are first acknowledged by the VI,
 178 before any responses to the request are returned. The response uses the standard
 179 command response format:
 180
 181     { "command_response": "diagnostic_request", "status": true}
 182
 183 **status** - true if the request was successfully created or cancelled.
 184
 185 When a node on the network response to the request and the result is published
 186 by the VI, the result looks like:
 187
 188     {"bus": 1,
 189       "message_id": 1234,
 190       "mode": 1,
 191       "pid": 5,
 192       "success": true,
 193       "payload": "0x1234",
 194       "value": 4660}
 195
 196 and to an unsuccessful request, with the `negative_response_code` and no `pid`
 197 echo:
 198
 199     {"bus": 1,
 200       "message_id": 1234,
 201       "mode": 1,
 202       "success": false,
 203       "negative_response_code": 17}
 204
 205 **bus** - the numerical identifier of the CAN bus where this response was
 206     received.
 207
 208 **message_id** - the CAN message ID for this response.
 209
 210 **mode** - the OBD-II mode of the original diagnostic request.
 211
 212 **pid** - (optional) the PID for the request, if applicable.
 213
 214 **success** -  true if the response received was a positive response. If this
 215   field is false, the remote node returned an error and the
 216   `negative_response_code` field should be populated.
 217
 218 **negative_response_code** - (optional)  If requested node returned an error,
 219     `success` will be `false` and this field will contain the negative response
 220     code (NRC).
 221
 222 Finally, the `payload` and `value` fields are mutually exclusive:
 223
 224 **payload** - (optional) up to 7 bytes of data returned in the response,
 225     represented as a hexadecimal number in a string. Many JSON parser cannot
 226     handle 64-bit integers, which is why we are not using a numerical data type.
 227
 228 **value** - (optional) if the response had a payload, this may be the
 229     payload interpreted as an integer.
 230
 231 The response to a simple PID request would look like this:
 232
 233     {"success": true, "bus": 1, "message_id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 234
 235 ## Commands
 236
 237 In addition to the `diagnostic_request` command described earlier, there are
 238 other possible values for the `command` field.
 239
 240 All commands immediately return a `command_response`, e.g.:
 241
 242     { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
 243
 244 **command_response** - an echo of the command this is a ACKing.
 245
 246 **status** - true if the command was understood and performed succesfully.
 247
 248 **message** - (optional) a string message from the VI, e.g. to return a version
 249     descriptor or error message.
 250
 251 ### Version Query
 252
 253 The `version` command triggers the VI to inject a firmware version identifier
 254 response into the outgoing data stream.
 255
 256 **Request**
 257
 258     { "command": "version"}
 259
 260 **Response**
 261
 262     { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
 263
 264 ### Device ID Query
 265
 266 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 267 MAC address of an included Bluetooth module) into into the outgoing data stream.
 268
 269 If no device ID is available, the response message will be "Unknown".
 270
 271 **Request**
 272
 273     { "command": "device_id"}
 274
 275 **Response**
 276
 277     { "command_response": "device_id", "message": "0012345678", "status": true}
 278
 279 ### Passthrough CAN Mode
 280
 281 The `passthrough` command controls whether low-level CAN messages are passed
 282 through from the CAN bus through the VI to the output stream. If the CAN
 283 acceptance filter is in bypass mode and passthrough is enabled, the output
 284 stream will include all received CAN messages. If the bypass filter is enabled,
 285 only those CAN messages that have been pre-defined in the firmware are
 286 forwarded.
 287
 288 **Request**
 289
 290     { "command": "passthrough",
 291       "bus": 1,
 292       "enabled": true
 293     }
 294
 295 **Response**
 296
 297 If the bus in the request was valid and the passthrough mode was changed, the
 298 `status` field in the response will be `true`. If `false`, the passthrough mode
 299 was not changed.
 300
 301     { "command_response": "passthrough", "status": true}
 302
 303 ### Acceptance Filter Bypass
 304
 305 The `af_bypass` command controls whether the CAN message acceptance filter is
 306 bypassed for each CAN controller. By default, hardware acceptance filter (AF) is
 307 enabled in the VI - only previously defined CAN message IDs will be received.
 308 Send this command with `bypass: true` to force the filters to bypassed.
 309
 310 If `passthrough` mode is also enabled, when the AF is bypassed, the output will
 311 include all CAN messages received.
 312
 313 **Request**
 314
 315     { "command": "af_bypass",
 316       "bus": 1,
 317       "bypass": true
 318     }
 319
 320 **Response**
 321
 322 If the bus in the request was valid and the AF mode was changed, the `status`
 323 field in the response will be `true`. If `false`, the passthrough mode was not
 324 changed.
 325
 326     { "command_response": "af_bypass", "status": true}
 327
 328 ### Payload Format Control
 329
 330 The `payload_format` command determines the format for output data from the VI
 331 and the expected format of commands sent to the VI.
 332
 333 Valid formats are `json` and `protobuf`.
 334
 335 **Request**
 336
 337     { "command": "payload_format",
 338       "format": "json"
 339     }
 340
 341 **Response**
 342
 343 If the format was changed successfully, the `status` in the response will be
 344 `true`. The response will be in the original message format, and all subsequent
 345 messages will be in the new format.
 346
 347     { "command_response": "payload_format", "status": true}
 348
 349 ### Automatic Pre-Defined OBD-II PID Requests
 350
 351 The `predefined_obd2` command enables and disables the querying for and
 352 translating of a set of pre-defined OBD-II PIDs from the attached vehicle. When
 353 enabled, the VI will query the vehicle to see if these PIDs are claimed to be
 354 supported and for those that are, it will set up recurring requests. The
 355 responses will be output as simple vehicle messages, with the names defined in
 356 the "Signals Defined from Diagnostic Messages" section below.
 357
 358 **Request**
 359
 360     { "command": "predefined_obd2",
 361       "enabled": true
 362     }
 363
 364 **Response**
 365
 366 If the predefined requests were enabled or disabled successfully, the `status` in
 367 the response will be `true`.
 368
 369     { "command_response": "predefined_obd2", "status": true}
 370
 371 ### C5 Cellular Configuration
 372
 373 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.
 374
 375 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.html) documentation.
 376
 377 Currently, only the ServerConnectSettings sub-message is supported in the vi-firmware's command interpreter. All other settings are currently compile-time only.
 378
 379 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.
 380
 381 **Request**
 382
 383     { "command": "modem_configuration",
 384       "server": {
 385                 "host": "www.myhost.com",
 386                 "port": 10000
 387           }
 388     }
 389
 390 **Response**
 391
 392         { "command_response": "modem_configuration", "status": true}
 393
 394 ## C5 SD Card Status
 395
 396 In order to check the status of the SD card, the following command is available:
 397
 398     { "command": "sd_mount_status"}
 399
 400 Command response if the SD card is mounted correctly:
 401
 402     { "command_response": "sd_mount_status", "status": true}
 403
 404 If the SD card is full, not enabled, or connected as a MSD, the device will respond with:
 405
 406     { "command_response": "sd_mount_status", "status": false}
 407
 408 For more info see [c5_msd](https://github.com/openxc/vi-firmware/docs/advanced/msd.html).
 409
 410 ## C5 RTC Configuration
 411
 412 To set the current time of the RTC, the following
 413
 414     { "command": "rtc_configuration", "unix_time": "1448551563"}
 415
 416 The response is
 417
 418     { "command_response": "rtc_configuration", "status": true}
 419
 420 For more info see [c5_rtc](https://github.com/openxc/vi-firmware/docs/advanced/rtc.html).
 421
 422 ## Extra Values
 423
 424 Any of the following JSON objects may optionally include an `extras`
 425 field. The value may be any valid JSON object or array. The client libraries
 426 will do their best to parse this information into a generic format and pass it
 427 to your application. For example:
 428
 429     {"name": "steering_wheel_angle",
 430         "value": 45,
 431         "extras": {
 432             "calibrated": false
 433         }
 434     }
 435