X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=c17eb6deaf653e408fd88b1c2bdd77fe1a68a217;hb=43f0abb2468b31d131b936ccf51844316426dc8a;hp=0fe4b8df30bcf4d83d1047b3b7943d025d948aa0;hpb=fd65f19af900c2462fc337dcdc1c61ff3a4d3452;p=apps%2Fagl-service-can-low-level.git diff --git a/README.md b/README.md index 0fe4b8df..c17eb6de 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,26 @@ # OpenXC Message Format Specification +Version: v0.3 + 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. + +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). -There are two valid message types - single valued and evented. +## 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} @@ -28,8 +36,7 @@ discrete pieces of information in the measurement. ## 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"} @@ -58,8 +65,7 @@ with this command format: "mode": 1, "pid": 5, "payload": "0x1234", - "parse_payload": true, - "multiple_response": false, + "multiple_responses": false, "factor": 1.0, "offset": 0, "frequency": 1, @@ -84,12 +90,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. -**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 @@ -97,26 +103,33 @@ 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. -**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). + +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. -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. +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: @@ -125,14 +138,24 @@ If you're just requesting a PID, you can use this minimal field set for the ### Responses +The response to a successful request: + {"bus": 1, "id": 1234, "mode": 1, "pid": 5, "success": true, - "negative_response_code": 17, "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. @@ -158,12 +181,11 @@ 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: - {"bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"} + {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"} ## Commands @@ -196,7 +218,8 @@ MAC address of an included Bluetooth module) into into the outgoing data stream. ## 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: @@ -253,11 +276,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 @@ -293,10 +316,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.