path: root/README.md

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

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

The expected format of a single valued message is:

    {"name": "steering_wheel_angle", "value": 45}

### Evented

The expected format of an event message is:

    {"name": "button_event", "value": "up", "event": "pressed"}

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

The format for a raw CAN message:

    {"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).

**id** - the CAN message ID

**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. 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. The `0x` prefix is
  optional.

### Diagnostic Messages

#### Requests

A diagnostic request is added or cancelled with a JSON object like this example:

    { "command": "diagnostic_request",
      "action": "add",
      "request": {
          "bus": 1,
          "id": 1234,
          "mode": 1,
          "pid": 5,
          "payload": "0x1234",
          "multiple_responses": false,
          "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.

**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
    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`
    is `0x01` - the complete string must have an even number of characters. The
    `0x` prefix is optional.

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

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

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

#### Responses

The response to a successful request:

    {"bus": 1,
      "id": 1234,
      "mode": 1,
      "pid": 5,
      "success": true,
      "payload": "0x1234",
      "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.

**id** - the CAN arbitration ID for this response.

**mode** - the OBD-II mode of the original diagnostic request.

**pid** - (optional) the PID for the request, if applicable.

**success** -  true if the response received was a positive response. If this
  field is false, the remote node returned an error and the
  `negative_response_code` field should be populated.

**negative_response_code** - (optional)  If requested node returned an error,
    `success` will be `false` and this field will contain the negative response
    code (NRC).

Finally, the `payload` and `value` fields are mutually exclusive:

**payload** - (optional) up to 7 bytes of data returned in the response,
    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.

**value** - (optional) if the response had a payload, this may be the
    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

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.

**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"}

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

```
{"metadata": {
    "version": "v3.0",
    "vehicle_interface_id": "7ABF",
    "vehicle": {
        "make": "Ford",
        "model": "Mustang",
        "trim": "V6 Premium",
        "year": 2013
    },
    "description": "highway drive to work",
    "driver_name": "TJ Giuli",
    "vehicle_id": "17N1039247929"
}
```

The following lines are OpenXC messages with a `timestamp` field added, e.g.:

    {"timestamp": 1385133351.285525, "name": "steering_wheel_angle", "value": 45}

The timestamp is in [UNIX time](http://en.wikipedia.org/wiki/Unix_time)
(i.e. seconds since the UNIX epoch, 00:00:00 UTC, 1/1/1970).

## Official Signals

These signal names are a part of the OpenXC specification, although some
manufacturers may support custom message names.

* steering_wheel_angle
    * numerical, -600 to +600 degrees
    * 10Hz
* torque_at_transmission
    * numerical, -500 to 1500 Nm
    * 10Hz
* engine_speed
    * numerical, 0 to 16382 RPM
    * 10Hz
* vehicle_speed
    * numerical, 0 to 655 km/h (this will be positive even if going in reverse
      as it's not a velocity, although you can use the gear status to figure out
      direction)
    * 10Hz
* accelerator_pedal_position
    * percentage
    * 10Hz
* parking_brake_status
    * boolean, (true == brake engaged)
    * 1Hz, but sent immediately on change
* brake_pedal_status
    * boolean (True == pedal pressed)
    * 1Hz, but sent immediately on change
* transmission_gear_position
    * states: first, second, third, fourth, fifth, sixth, seventh, eighth,
      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, seventh, eighth, ninth, tenth
    * 1Hz, but sent immediately on change
* odometer
    * Numerical, km
        0 to 16777214.000 km, with about .2m resolution
    * 10Hz
* ignition_status
    * states: off, accessory, run, start
    * 1Hz, but sent immediately on change
* fuel_level
    * percentage
    * 2Hz
* fuel_consumed_since_restart
    * numerical, 0 - 4294967295.0 L (this goes to 0 every time the vehicle
      restarts, like a trip meter)
    * 10Hz
* door_status
    * Value is State: driver, passenger, rear_left, rear_right.
    * Event is boolean: true == ajar
    * 1Hz, but sent immediately on change
* headlamp_status
    * boolean, true is on
    * 1Hz, but sent immediately on change
* high_beam_status
    * boolean, true is on
    * 1Hz, but sent immediately on change
* windshield_wiper_status
    * boolean, true is on
    * 1Hz, but sent immediately on change
* latitude
    * numerical, -89.0 to 89.0 degrees with standard GPS accuracy
    * 1Hz
* longitude
    * 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-2014 Ford Motor Company

Licensed under the BSD license.

[OpenXC]: http://openxcplatform.com