summaryrefslogtreecommitdiffstats
path: root/CAN-binder/libs/openxc-message-format/JSON.mkd
blob: d320aad08e9a7dae4dc03586d0c913d83f57b6af (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
# OpenXC JSON Message Format

Each JSON message published by a VI is delimited with a `\0 ` character.

## Table of Contents
1. [Vehicle Messages](#vehicle-messages)
2. [CAN Message](#can-message)
3. [Diagnostic Message](#diagnostic-message)
4. [Commands](#commands)
5. [Extra Values](#extra-values)

## Vehicle Messages

### Simple Vehicle Message

There may not be a 1:1 relationship between input and output signals - i.e.
engine timing CAN signals may be summarized in an "engine performance" metric on
the abstract side of the interface.

The expected format of a single valued message is:

    {"name": "steering_wheel_angle", "value": 45}

### Evented Simple Vehicle Message

The expected format of an event message is:

    {"name": "button_event", "value": "up", "event": "pressed"}

This format is good for something like a button event, where there are two
discrete pieces of information in the measurement.

## CAN Message

The format for a plain CAN message:

    {"bus": 1, "id": 1234, "data": "0x12345678"}

**bus** - the numerical identifier of the CAN bus where this message originated,
  most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).

**id** - the CAN message ID

**data** - up to 8 bytes of data from the CAN message's payload, represented as
  a hexidecimal number in a string. Many JSON parser cannot handle 64-bit
  integers, which is why we are not using a numerical data type. Each byte in
  the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the
  complete string must have an even number of characters. The `0x` prefix is
  optional.

**format** - (optional) explicitly set the frame format for the CAN message, one
  of `standard` or `extended`. If the `id` is greater than `0x7ff`, the extended
  frame format will be selected automatically.

## Diagnostic Message

### Requests

A diagnostic request is added or cancelled with a JSON object like this example:

    { "command": "diagnostic_request",
      "action": "add",
      "diagnostic_request": {
          "bus": 1,
          "message_id": 1234,
          "mode": 1,
          "pid": 5,
          "payload": "0x1234",
          "multiple_responses": false,
          "frequency": 1,
          "name": "my_pid"
        }
      }
    }

* The `command` must be `diagnostic_request.`
* The `action` must be included, and must be one of:
    * `add` - create a new one-off or recurring diagnostic request.
    * `cancel` - cancel an existing request.
* The details of the request must be included in the `request` field, using
  the sub-fields defined below.

A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
combine to create a unique key to identify a request. These four fields will be
referred to as the key of the diagnostic request. For example, to create a
simple one-time diagnostic request:

    { "command": "diagnostic_request",
      "action": "add",
      "diagnostic_request": {
          "bus": 1,
          "message_id": 1234,
          "mode": 1,
          "pid": 5
        }
      }
    }

Requests are completed after any responses are received (unless
`multiple_responses` is set), or the request has timed out after a certain
number of seconds. After a request is completed, you can re-`create` the same
key to make another request.

Requests with a `frequency` are added as *recurring* requests, e.g. to add the
previous example as a recurring request at 1Hz:

    { "command": "diagnostic_request",
      "action": "add",
      "diagnostic_request": {
          "bus": 1,
          "message_id": 1234,
          "mode": 1,
          "pid": 5,
          "frequency": 1
        }
      }
    }

To cancel a recurring request, send a `cancel` action with the same key, e.g.:

    { "command": "diagnostic_request",
      "action": "cancel",
      "diagnostic_request": {
          "bus": 1,
          "message_id": 1234,
          "mode": 1,
          "pid": 5
        }
      }
    }

Simultaneous recurring requests for the same key at different rates (e.g. 1Hz
*and* 2Hz) is not supported. However, non-recurring ("one-off") requests may
exist in parallel with a recurring request for the same key.

**bus** - the numerical identifier of the CAN bus where this request should be
    sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).

**message_id** - the CAN message ID for the request.

**mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
    standardized modes and 0x22 is a common proprietary mode).

**pid** - (optional) the PID for the request, if applicable.

**payload** - (optional) up to 7 bytes of data for the request's payload
    represented as a hexadecimal number in a string. Many JSON parser cannot
    handle 64-bit integers, which is why we are not using a numerical data type.
    Each byte in the string *must* be represented with 2 characters, e.g. `0x1`
    is `0x01` - the complete string must have an even number of characters. The
    `0x` prefix is optional.

**name** - (optional, defaults to nothing) A human readable, string name for
  this request. If provided, the response will have a `name` field (much like a
  simple vehicle message) with this value in place of `bus`, `id`, `mode` and
  `pid`.

**multiple_responses** - (optional, false by default) if true, request will stay
  active for a full 100ms, even after receiving a diagnostic response message.
  This is useful for requests to the functional broadcast message ID
  (`0x7df`) when you need to get responses from multiple modules. It's possible
  to set this to `true` for non-broadcast requests, but in practice you won't
  see any additional responses after the first and it will just take up memory
  in the VI for longer.

**frequency** - (optional) Make this request a recurring request, at a this
  frequency in Hz. To send a single non-recurring request, leave this field out.

**decoded_type** - (optional, defaults to "obd2" if the request is a recognized
OBD-II mode 1 request, otherwise "none") If specified, the valid values are
`"none"` and `"obd2"`. If `obd2`, the payload will be decoded according to the
OBD-II specification and returned in the `value` field. Set this to `none` to
manually override the OBD-II decoding feature for a known PID.

### Responses

Requests to add or cancel a diagnostic request are first acknowledged by the VI,
before any responses to the request are returned. The response uses the standard
command response format:

    { "command_response": "diagnostic_request", "status": true}

**status** - true if the request was successfully created or cancelled.

When a node on the network response to the request and the result is published
by the VI, the result looks like:

    {"bus": 1,
      "message_id": 1234,
      "mode": 1,
      "pid": 5,
      "success": true,
      "payload": "0x1234",
      "value": 4660}

and to an unsuccessful request, with the `negative_response_code` and no `pid`
echo:

    {"bus": 1,
      "message_id": 1234,
      "mode": 1,
      "success": false,
      "negative_response_code": 17}

**bus** - the numerical identifier of the CAN bus where this response was
    received.

**message_id** - the CAN message ID for this response.

**mode** - the OBD-II mode of the original diagnostic request.

**pid** - (optional) the PID for the request, if applicable.

**success** -  true if the response received was a positive response. If this
  field is false, the remote node returned an error and the
  `negative_response_code` field should be populated.

**negative_response_code** - (optional)  If requested node returned an error,
    `success` will be `false` and this field will contain the negative response
    code (NRC).

Finally, the `payload` and `value` fields are mutually exclusive:

**payload** - (optional) up to 7 bytes of data returned in the response,
    represented as a hexadecimal number in a string. Many JSON parser cannot
    handle 64-bit integers, which is why we are not using a numerical data type.

**value** - (optional) if the response had a payload, this may be the
    payload interpreted as an integer.

The response to a simple PID request would look like this:

    {"success": true, "bus": 1, "message_id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}

## Commands

In addition to the `diagnostic_request` command described earlier, there are
other possible values for the `command` field.

All commands immediately return a `command_response`, e.g.:

    { "command_response": "version", "message": "v6.0-dev (default)", "status": true}

**command_response** - an echo of the command this is a ACKing.

**status** - true if the command was understood and performed succesfully.

**message** - (optional) a string message from the VI, e.g. to return a version
    descriptor or error message.

### Version Query

The `version` command triggers the VI to inject a firmware version identifier
response into the outgoing data stream.

**Request**

    { "command": "version"}

**Response**

    { "command_response": "version", "message": "v6.0-dev (default)", "status": true}

### Device ID Query

The `device_id` command triggers the VI to inject a unique device ID (e.g. the
MAC address of an included Bluetooth module) into into the outgoing data stream.

If no device ID is available, the response message will be "Unknown".

**Request**

    { "command": "device_id"}

**Response**

    { "command_response": "device_id", "message": "0012345678", "status": true}

### Passthrough CAN Mode

The `passthrough` command controls whether low-level CAN messages are passed
through from the CAN bus through the VI to the output stream. If the CAN
acceptance filter is in bypass mode and passthrough is enabled, the output
stream will include all received CAN messages. If the bypass filter is enabled,
only those CAN messages that have been pre-defined in the firmware are
forwarded.

**Request**

    { "command": "passthrough",
      "bus": 1,
      "enabled": true
    }

**Response**

If the bus in the request was valid and the passthrough mode was changed, the
`status` field in the response will be `true`. If `false`, the passthrough mode
was not changed.

    { "command_response": "passthrough", "status": true}

### Acceptance Filter Bypass

The `af_bypass` command controls whether the CAN message acceptance filter is
bypassed for each CAN controller. By default, hardware acceptance filter (AF) is
enabled in the VI - only previously defined CAN message IDs will be received.
Send this command with `bypass: true` to force the filters to bypassed.

If `passthrough` mode is also enabled, when the AF is bypassed, the output will
include all CAN messages received.

**Request**

    { "command": "af_bypass",
      "bus": 1,
      "bypass": true
    }

**Response**

If the bus in the request was valid and the AF mode was changed, the `status`
field in the response will be `true`. If `false`, the passthrough mode was not
changed.

    { "command_response": "af_bypass", "status": true}

### Payload Format Control

The `payload_format` command determines the format for output data from the VI
and the expected format of commands sent to the VI.

Valid formats are `json` and `protobuf`.

**Request**

    { "command": "payload_format",
      "format": "json"
    }

**Response**

If the format was changed successfully, the `status` in the response will be
`true`. The response will be in the original message format, and all subsequent
messages will be in the new format.

    { "command_response": "payload_format", "status": true}

### Automatic Pre-Defined OBD-II PID Requests

The `predefined_obd2` command enables and disables the querying for and
translating of a set of pre-defined OBD-II PIDs from the attached vehicle. When
enabled, the VI will query the vehicle to see if these PIDs are claimed to be
supported and for those that are, it will set up recurring requests. The
responses will be output as simple vehicle messages, with the names defined in
the "Signals Defined from Diagnostic Messages" section below.

**Request**

    { "command": "predefined_obd2",
      "enabled": true
    }

**Response**

If the predefined requests were enabled or disabled successfully, the `status` in
the response will be `true`.

    { "command_response": "predefined_obd2", "status": true}

### C5 Cellular Configuration

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.

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. 

Currently, only the ServerConnectSettings sub-message is supported in the vi-firmware's command interpreter. All other settings are currently compile-time only.

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.

**Request**

    { "command": "modem_configuration",
      "server": {
		"host": "www.myhost.com",
		"port": 10000
	  }
    }

**Response**

	{ "command_response": "modem_configuration", "status": true}

## C5 SD Card Status

In order to check the status of the SD card, the following command is available:

    { "command": "sd_mount_status"}
    
Command response if the SD card is mounted correctly:

    { "command_response": "sd_mount_status", "status": true}
    
If the SD card is full, not enabled, or connected as a MSD, the device will respond with:

    { "command_response": "sd_mount_status", "status": false}
    
For more info see [c5_msd](https://github.com/openxc/vi-firmware/docs/advanced/msd.html).

## C5 RTC Configuration

To set the current time of the RTC, the following

    { "command": "rtc_configuration", "unix_time": "1448551563"}
    
The response is

    { "command_response": "rtc_configuration", "status": true}

For more info see [c5_rtc](https://github.com/openxc/vi-firmware/docs/advanced/rtc.html).

## Extra Values

Any of the following JSON objects may optionally include an `extras`
field. The value may be any valid JSON object or array. The client libraries
will do their best to parse this information into a generic format and pass it
to your application. For example:

    {"name": "steering_wheel_angle",
        "value": 45,
        "extras": {
            "calibrated": false
        }
    }