Add passthrough command and refactor commands in binary format.

[apps/agl-service-can-low-level.git] / README.md

diff --git a/README.md b/README.md
index 3e496bd..feb40c4 100644 (file)
--- a/README.md
+++ b/README.md
@@ -9,9 +9,13 @@ interfaces (e.g. USB or Bluetooth) as JSON or Protocol Buffers (protobuf).
 
 ## Binary (Protocol Buffers)
 
 
 ## Binary (Protocol Buffers)
 

-The Protocol Buffer format is specified in the file `openxc.proto`. Those are
-published using the standard length-delimited method (any protobuf library
-should support this).
+The binary format is encoded using [Google Protocol
+Buffers](https://code.google.com/p/protobuf/). The format is specified in the
+file `openxc.proto`. Those are published using the standard length-delimited
+method (any protobuf library should support this).
+
+The binary format is best if you need to maximize the amount of data that can be
+sent from the VI, trading off flexibility for efficiency.

 
 ## JSON
 
 
 ## JSON
 


@@ -19,6 +23,9 @@ This document describes the JSON format and includes a high level description of
 each type and field. Each JSON message published by a VI is delimited with a
 `\0 ` character.
 
 each type and field. Each JSON message published by a VI is delimited with a
 `\0 ` character.
 

+The JSON format is best for most developers, as it is fairly efficient and very
+flexible.
+

 ### Extra Values
 
 Any of the following JSON objects may optionally include an `extras`
 ### Extra Values
 
 Any of the following JSON objects may optionally include an `extras`


@@ -26,7 +33,8 @@ 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:
 
 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,
+    {"name": "steering_wheel_angle",
+        "value": 45,

         "extras": {
             "calibrated": false
         }
         "extras": {
             "calibrated": false
         }


@@ -66,16 +74,17 @@ The format for a raw CAN message:
   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
   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.
+  complete string must have an even number of characters. The `0x` prefix is
+  optional.

 
 ### Diagnostic Messages
 
 #### Requests
 
 
 ### Diagnostic Messages
 
 #### Requests
 

-A request to add or update a diagnostic request is sent to a vehicle interface
-with this command format:
+A diagnostic request is added or cancelled with a JSON object like this example:

 
     { "command": "diagnostic_request",
 
     { "command": "diagnostic_request",

+      "action": "add",

       "request": {
           "bus": 1,
           "id": 1234,
       "request": {
           "bus": 1,
           "id": 1234,


@@ -89,21 +98,82 @@ with this command format:
       }
     }
 
       }
     }
 

+* 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",
+      "request": {
+          "bus": 1,
+          "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",
+      "request": {
+          "bus": 1,
+          "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",
+      "request": {
+          "bus": 1,
+          "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).
 
 **id** - the CAN arbitration ID for the request.
 
 **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).
 
 **id** - the CAN arbitration ID for the request.
 

-**mode** - the OBD-II mode of the request - 1 through 255 (1 through 9 are the
+**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
     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 hexidecimal number in a string. Many JSON parser cannot
+    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`
     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.
+    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
 
 **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


@@ -118,9 +188,8 @@ with this command format:
   see any additional responses after the first and it will just take up memory
   in the VI for longer.
 
   see any additional responses after the first and it will just take up memory
   in the VI for longer.
 

-**frequency** - (optional, defaults to 0) The frequency in Hz to send this
-    request. To send a single non-recurring request, set this to 0 or leave it
-    out.
+**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
 
 **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


@@ -128,29 +197,6 @@ OBD-II mode 1 request, otherwise "none") If specified, the valid values are
 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.
 
 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.
 

-A diagnostic request's `bus`, `id`, `mode` and `pid` (or lack of a `pid`)
-combine to create a unique key to identify a recurring request. This means that
-you cannot simultaneosly have recurring requests at 2Hz and 5Hz for the same PID
-from the same ID.
-
-If you send a new `diagnostic_request` command with a `bus + id + mode + pid`
-key matching an existing recurring request, it will update it with whatever
-other parameters you've provided (e.g. it will change the frequency if you
-specify one).
-
-To cancel a recurring request, send a `diagnostic_request` command with the
-matching request information (i.e. the `bus`, `id`, `mode` and `pid`) but a
-frequency of 0.
-
-Non-recurring requests may have the same `bus+id+mode(+pid)` key as a recurring
-request, and they will co-exist without issue. As soon as a non-recurring
-request is either completed or times out, it is removed from the active list.
-
-If you're just requesting a PID, you can use this minimal field set for the
-`request` object:
-
-    {"bus": 1, "id": 1234, "mode": 1, "pid": 5}
-

 #### Responses
 
 The response to a successful request:
 #### Responses
 
 The response to a successful request:


@@ -204,6 +250,9 @@ The response to a simple PID request would look like this:
 
 ### Commands
 
 
 ### Commands
 

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

 #### Version Query
 
 The `version` command triggers the VI to inject a firmware version identifier
 #### Version Query
 
 The `version` command triggers the VI to inject a firmware version identifier


@@ -230,6 +279,33 @@ MAC address of an included Bluetooth module) into into the outgoing data stream.
 
     { "command_response": "device_id", "message": "0012345678"}
 
 
     { "command_response": "device_id", "message": "0012345678"}
 

+#### Passthrough CAN Mode
+
+The `passthrough` command controls the passthrough mode for each of the CAN
+buses. There are three passthrough modes:
+
+* `off` - Only the specified simple vehicle messages are processed and output
+  from the VI.
+* `filtered` - If the CAN acceptance filter is not otherwise disabled, only the
+  pre-defined CAN messages (i.e. those compiled with the firmware) will be
+  output in the low-level CAN format from VI.
+* `unfiltered` - All received CAN messages will be passed through from the bus
+  to the VI's output.
+
+**Request**
+
+    { "command": "passthrough"
+      "bus": 1,
+      "mode":
+    }
+
+**Response**
+
+If the bus and mode in the request were recognized, the `status` field in the
+response will be `true`. If `false`, the passthrough mode was not changed.
+
+    { "command_response": "passthrough", "status": true}
+

 ### Trace File Format
 
 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
 ### Trace File Format
 
 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,