X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=f26c5d1bd89270c9785967374982a9a2e95892e2;hb=5e0b413db0e57659bd6e654566d9aad5fc00e1e8;hp=475ae21560174e1defa1a5e4ea39e6939aa727b9;hpb=929ab4bd49789e592e0192f3e5f4a06c499db135;p=apps%2Fagl-service-can-low-level.git diff --git a/README.md b/README.md index 475ae215..f26c5d1b 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,22 @@ 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). -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. + +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. -## Single Valued - The expected format of a single valued message is: {"name": "steering_wheel_angle", "value": 45} @@ -28,8 +34,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"} @@ -40,21 +45,32 @@ is sent as a JSON object, separated by newlines. The format of each object is: **data** - up to 8 bytes of data from the CAN message's payload, represented as 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. + 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. ## Diagnostic Messages ### Requests - {"bus": 1, - "id": 1234, - "mode": 1, - "pid": 5, - "payload": "0x1234", - "parse_payload": true, - "factor": 1.0, - "offset": 0, - "frequency": 0} +A request to add or update a diagnostic request is sent to a vehicle interface +with this command format: + + { "command": "diagnostic_request", + "request": { + "bus": 1, + "id": 1234, + "mode": 1, + "pid": 5, + "payload": "0x1234", + "multiple_responses": false, + "factor": 1.0, + "offset": 0, + "frequency": 1, + "name": "my_pid" + } + } + } **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). @@ -69,41 +85,75 @@ is sent as a JSON object, separated by newlines. The format of each object is: **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 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. + +**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_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 + to set this to `true` for non-broadcast requests, but in practice you won't + see any additional responses after the first and it will just take up memory + in the VI for longer. -**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'. +**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. -**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`. +**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). -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 +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. -If you're just requesting a PID, you can use a simplified format for the -request: +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 +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. @@ -129,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 - 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 + +### 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** -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 + { "command_response": "device_id", "message": "0012345678"} ## 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: