Standardize names for payload format.

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

diff --git a/README.md b/README.md
index 50c166b..e127543 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,77 @@ 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 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}
+
+
 ### Trace File Format
 
 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,