Remove unnecessary 'bus' field from message format command.

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

diff --git a/README.md b/README.md
index 65f0d19..2cde130 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,23 +1,56 @@
 # OpenXC Message Format Specification
 
 # OpenXC Message Format Specification
 

+Version: v0.4-dev
+

 This specification is a part of the [OpenXC platform][OpenXC].
 
 An OpenXC vehicle interface sends generic vehicle data over one or more output
 This specification is a part of the [OpenXC platform][OpenXC].
 
 An OpenXC vehicle interface sends generic vehicle data over one or more output

-interfaces (e.g. USB or Bluetooth) as JSON objects, separated by newlines.
+interfaces (e.g. USB or Bluetooth) as JSON or Protocol Buffers (protobuf).
+
+## Binary (Protocol Buffers)
+
+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
+
+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.
+
+The JSON format is best for most developers, as it is fairly efficient and very
+flexible.

 
 

-There are two valid message types - single valued and evented.
+### 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
+        }
+    }
+
+### Single Valued

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

-## Single Valued
-

 The expected format of a single valued message is:
 
     {"name": "steering_wheel_angle", "value": 45}
 
 The expected format of a single valued message is:
 
     {"name": "steering_wheel_angle", "value": 45}
 

-## Evented
+### Evented

 
 The expected format of an event message is:
 
 
 The expected format of an event message is:
 


@@ -26,12 +59,11 @@ The expected format of an event message is:
 This format is good for something like a button event, where there are two
 discrete pieces of information in the measurement.
 
 This format is good for something like a button event, where there are two
 discrete pieces of information in the measurement.
 

-## Raw CAN Message format
+### Raw CAN Message format

 
 

-An OpenXC vehicle interface may also output raw CAN messages. Each CAN message
-is sent as a JSON object, separated by newlines. The format of each object is:
+The format for a raw CAN message:

 
 

-    {"bus": 1, "id": 1234, "value": "0x12345678"}
+    {"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).
 
 **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).


@@ -42,54 +74,113 @@ is sent as a JSON object, separated by newlines. The format of each object is:
   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
+### Diagnostic Messages

 
 

-### Requests
+#### 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,
           "mode": 1,
           "pid": 5,
           "payload": "0x1234",
       "request": {
           "bus": 1,
           "id": 1234,
           "mode": 1,
           "pid": 5,
           "payload": "0x1234",

-          "parse_payload": true,
-          "multiple_response": false,
-          "factor": 1.0,
-          "offset": 0,
+          "multiple_responses": false,

           "frequency": 1,
           "name": "my_pid"
         }
       }
     }
 
           "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",
+      "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 15 (1 through 9 are the
-    standardized modes).
+**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
 
 **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.

 
 

-**parse_payload** - (optional, false by default) if true, the complete payload in the
-    response message will be parsed as a number and returned in the 'value' field of
-    the response. The 'payload' field will be omitted in responses with a
-    'value'.
+**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
+  normal translated message) with this value in place of `bus`, `id`, `mode` and
+  `pid`.

 
 

-**multiple_response** - (optional, false by default) if true, request will stay
+**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 arbitration ID
   (`0x7df`) when you need to get responses from multiple modules. It's possible
   active for a full 100ms, even after receiving a diagnostic response message.
   This is useful for requests to the functional broadcast arbitration ID
   (`0x7df`) when you need to get responses from multiple modules. It's possible


@@ -97,42 +188,35 @@ 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.
 

-**factor** - (optional, 1.0 by default) if `parse_payload` is true, the value in
-    the payload will be multiplied by this factor before returning. The `factor`
-    is applied before the `offset`.
+**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.

 
 

-**offset** - (optional, 0 by default) if `parse_payload` is true, this offset
-    will be added to the value in the payload before returning. The `offset` is
-    applied after the `factor`.
+**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.

 
 

-**frequency** - (optional, defaults to 0) The frequency in Hz to send this
-    request. To send a single request, set this to 0 or leave it out.
+#### Responses

 
 

-**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
-    normal translated message) in place of the request details (i.e. the bus,
-    id, mode and pid).  TODO elaborate on this.
-
-The `bus+id+mode+pid` key is unique, so if you send a create request with that
-key twice, it'll overwrite the existing one (i.e. it will change the frequency,
-the only other parameter). To cancel a recurring request, send this command with
-the frequency set to 0.
-
-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:

 
     {"bus": 1,
       "id": 1234,
       "mode": 1,
       "pid": 5,
       "success": true,
 
     {"bus": 1,
       "id": 1234,
       "mode": 1,
       "pid": 5,
       "success": true,

-      "negative_response_code": 17,

       "payload": "0x1234",
       "payload": "0x1234",

-      "parsed_payload": 4660}
+      "value": 4660}
+
+and to an unsuccessful request, with the `negative_response_code` and no `pid`
+echo:
+
+    {"bus": 1,
+      "id": 1234,
+      "mode": 1,
+      "success": false,
+      "negative_response_code": 17}

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


@@ -158,16 +242,18 @@ Finally, the `payload` and `value` fields are mutually exclusive:
     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
     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 and transformed with a factor and offset
-    provided with the request.
+    payload interpreted as an integer.

 
 The response to a simple PID request would look like this:
 
     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 
 
 The response to a simple PID request would look like this:
 
     {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 

-## Commands
+### Commands

 
 

-### Version Query
+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
 response into the outgoing data stream.
 
 The `version` command triggers the VI to inject a firmware version identifier
 response into the outgoing data stream.


@@ -180,7 +266,7 @@ response into the outgoing data stream.
 
     { "command_response": "version", "message": "v6.0-dev (default)"}
 
 
     { "command_response": "version", "message": "v6.0-dev (default)"}
 

-### Device ID Query
+#### 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.
 
 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.


@@ -193,10 +279,82 @@ 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"}
 

-## Trace File Format
+#### 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}
+
+#### Message Format Control
+
+The `message_format` command determines the format for output data from the VI
+and also the expected format of commands sent to the VI.
+
+Valid formats are `json` and `binary`.
+
+**Request**
+
+    { "command": "message_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": "message_format", "status": true}
+
+
+### Trace File Format

 
 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,
 
 An OpenXC vehicle trace file is a plaintext file that contains JSON objects,

-separated by newlines.
+separated by newlines (which may be either `\r\n` or `\n`, depending on the
+platform the trace file was recorded).

 
 The first line may be a metadata object, although this is optional:
 
 
 The first line may be a metadata object, although this is optional:
 


@@ -253,11 +411,11 @@ manufacturers may support custom message names.
     * 1Hz, but sent immediately on change
 * transmission_gear_position
     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
     * 1Hz, but sent immediately on change
 * transmission_gear_position
     * states: first, second, third, fourth, fifth, sixth, seventh, eighth,

-      reverse, neutral
+      ninth, tenth, reverse, neutral

     * 1Hz, but sent immediately on change
 * gear_lever_position
     * states: neutral, park, reverse, drive, sport, low, first, second, third,
     * 1Hz, but sent immediately on change
 * gear_lever_position
     * states: neutral, park, reverse, drive, sport, low, first, second, third,

-      fourth, fifth, sixth
+      fourth, fifth, sixth, seventh, eighth, ninth, tenth

     * 1Hz, but sent immediately on change
 * odometer
     * Numerical, km
     * 1Hz, but sent immediately on change
 * odometer
     * Numerical, km


@@ -293,10 +451,31 @@ manufacturers may support custom message names.
     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
     * 1Hz
 
     * numerical, -179.0 to 179.0 degrees with standard GPS accuracy
     * 1Hz
 

+### Signals from Diagnostics Messages
+
+This set of signals is often retreived from OBD-II requests. The units can be
+found in the [OBD-II standard](http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01).
+
+* engine_load
+* engine_coolant_temperature
+* barometric_pressure
+* commanded_throttle_position
+* throttle_position
+* fuel_level
+* intake_air_temperature
+* intake_manifold_pressure
+* running_time
+* fuel_pressure
+* mass_airflow
+* accelerator_pedal_position
+* ethanol_fuel_percentage
+* engine_oil_temperature
+* engine_torque
+

 License
 =======
 
 License
 =======
 

-Copyright (c) 2012-2013 Ford Motor Company
+Copyright (c) 2012-2014 Ford Motor Company

 
 Licensed under the BSD license.
 
 
 Licensed under the BSD license.