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 50c166b..feb40c4 100644 (file)
--- a/README.md
+++ b/README.md
@@ -74,7 +74,8 @@ 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
-  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
 
@@ -162,7 +163,7 @@ exist in parallel with a recurring request for the same key.
 
 **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.
@@ -171,7 +172,8 @@ exist in parallel with a recurring request for the same key.
     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.
+    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
@@ -277,6 +279,33 @@ MAC address of an included Bluetooth module) into into the outgoing data stream.
 
     { "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,