X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=6c4e23b7b6cecf1a19e05f3860f22514d35522ef;hb=9e854584b0182c545ce80b256b236edf811e233a;hp=cef6ea376698f6cedb1e0a01babc8453fe3471b7;hpb=f3f00874c637bcd700ded55f39cee5b1a881bc7c;p=apps%2Flow-level-can-service.git diff --git a/README.md b/README.md index cef6ea3..6c4e23b 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,35 @@ # 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 -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 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). + +## JSON -There are two valid message types - single valued and evented. +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. + +### 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. -## Single Valued - 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: @@ -26,12 +38,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. -## 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). @@ -44,9 +55,9 @@ is sent as a JSON object, separated by newlines. The format of each object is: the string *must* be represented with 2 characters, e.g. `0x1` is `0x01` - the complete string must have an even number of characters. -## 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: @@ -58,10 +69,7 @@ with this command format: "mode": 1, "pid": 5, "payload": "0x1234", - "parse_payload": true, "multiple_responses": false, - "factor": 1.0, - "offset": 0, "frequency": 1, "name": "my_pid" } @@ -84,11 +92,6 @@ 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. -**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 @@ -102,28 +105,40 @@ with this command format: 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. + +**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. -**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`. +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. -**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. +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. + +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 +#### Responses The response to a successful request: @@ -168,16 +183,15 @@ 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 - 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"} -## Commands +### Commands -### Version Query +#### Version Query The `version` command triggers the VI to inject a firmware version identifier response into the outgoing data stream. @@ -190,7 +204,7 @@ response into the outgoing data stream. { "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. @@ -203,10 +217,11 @@ MAC address of an included Bluetooth module) into into the outgoing data stream. { "command_response": "device_id", "message": "0012345678"} -## Trace File Format +### 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: @@ -263,11 +278,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, - 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, - fourth, fifth, sixth + fourth, fifth, sixth, seventh, eighth, ninth, tenth * 1Hz, but sent immediately on change * odometer * Numerical, km @@ -303,10 +318,31 @@ manufacturers may support custom message names. * 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 ======= -Copyright (c) 2012-2013 Ford Motor Company +Copyright (c) 2012-2014 Ford Motor Company Licensed under the BSD license.