Merge remote-tracking branch 'origin/master' into next

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

diff --git a/README.md b/README.md
index 01ca5f3..9ff9b2e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,18 +1,26 @@
 # 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).
+
+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.

 
 

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


@@ -28,10 +36,9 @@ 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).


@@ -58,10 +65,7 @@ with this command format:
           "mode": 1,
           "pid": 5,
           "payload": "0x1234",
           "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"
         }


@@ -84,12 +88,12 @@ with this command format:
     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.
 
     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.
 

-**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,29 +101,33 @@ 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, 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.

 
 

-**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.
+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.

 
 

-**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.
+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).

 
 

-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.
+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.

 
 

-TODO it'd be nice to have the OBD-II PIDs built in, with the proper conversion
-functions - that may need a different output format
+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:
 
 If you're just requesting a PID, you can use this minimal field set for the
 `request` object:


@@ -128,14 +136,24 @@ If you're just requesting a PID, you can use this minimal field set for the
 
 ### Responses
 
 
 ### 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.


@@ -161,21 +179,45 @@ 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:
 
 
 The response to a simple PID request would look like this:
 

-    {"bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
+    {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
+
+## Commands

 
 

-TODO again, it'd be nice to have the OBD-II PIDs built in, with the proper
-conversion functions so the response here included the actual transformed value
-of the pid and a human readable name
+### 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)"}
+
+### 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.
+
+**Request**
+
+    { "command": "device_id"}
+
+**Response**
+
+    { "command_response": "device_id", "message": "0012345678"}

 
 ## 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,

-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:
 


@@ -232,11 +274,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


@@ -272,10 +314,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.