Custom PIDs

Extended Parameters

How to extend Electric Sidecar's functionality with custom parameters

What are Extended Parameters?

Extended Parameter IDs, or PIDs, are special codes used in the OBD-II (On-Board Diagnostics) system of vehicles to request data from a vehicle's electronic control unit (ECU). While standard PIDs provide basic data like vehicle speed and engine RPM, extended PIDs can offer more specific and detailed information, which can be crucial for advanced diagnostics.

For newer vehicles, especially electric vehicles, extended PIDs are often the only way to get information about the vehicle over OBD-II.

Extended PIDs in Electric Sidecar

In addition to supporting many of the industry standard OBD-II PIDs specified in SAE J1979, Electric Sidecar supports extended PIDs through its community GitHub organization, github.com/electricsidecar.

Every vehicle make and model has its own GitHub repository in the Electric Sidecar organization. If a make and model you're interested in is not yet available, send an email with your requested make and model to support@electricsidecar.app or open an issue.

When you connect a scanner to your car, Electric Sidecar will ask for the car's VIN in order to determine its make and model. The make and model will then be used to enable the relevant extended PIDs within the app.

All extended PIDs are licensed under a CC BY-SA 4.0 license.

Contributing extended PIDs

Contributions from the automotive community help expand the library of extended PIDs available in Electric Sidecar. By sharing extended PIDs, we all contribute to the ability for car owners to access more of their vehicle data.

To contribute an extended PID you must first fork the GitHub repository for the relevant make and model on github.com/electricsidecar.

Extended PIDs are stored at the following path in each repository:

signalsets/v3/default.json
    

Examples


Extended PID file format

Extended PIDs are stored in a JSON file format using the following top level specification:

{
  "commands": [Command]
  "signalGroups": [SignalGroup]?
}
    

Complete example

{
  "commands": [{
    "hdr": "713",
    "rax": "77D",
    "cmd": {"22": "2B1B"},
    "freq": 0.25,
    "signals": [{
      "id": "TAYCAN_TIRE_FL_SPD",
      "path": "Movement",
      "fmt": {
        "len": 16,
        "max": 1000,
        "mul": 0.05625,
        "unit": "kilometersPerHour"
      },
      "name": "Front left wheel speed"
    }]
  }]
}
    

Properties


Command

Commands represent a single OBD-II message that can be sent to the vehicle. The vehicle will typically respond to a Command with one or more Signals. Commands define the format of the Signals they expect to receive.

Example

{
  "commands": [{
    "hdr": "713",
    "rax": "77D",
    "cmd": {"22": "2B1B"},
    "freq": 0.25,
    "signals": [{
      "id": "TAYCAN_TIRE_FL_SPD",
      "path": "Movement",
      "fmt": {
        "len": 16,
        "max": 1000,
        "mul": 0.05625,
        "unit": "kilometersPerHour"
      },
      "name": "Front left wheel speed"
    }]
  }]
}
    

Required properties

Optional properties


Connectable

Connectables are elements of the Electric Sidecar user interface that can be powered by values returned from an OBD-II scanner. Connectables expect their values to be provided in a certain Unit.

Example

{
  "commands": [{
    "hdr": "7E0",
    "rax": "7E8",
    "cmd": {"22": "1156"},
    "freq": 1,
    "signals": [{
      "id": "TAYCAN_HVBAT_SOC",
      "path": "Battery",
      "fmt": {
        "len": 8,
        "max": 100,
        "mul": 0.5,
        "unit": "percent"
      },
      "name": "HV battery charge",
      "suggestedMetric": "stateOfCharge"
    }]
  }]
}
    

Available Connectables


Format

Formats define how to decode a signal as a human-readable value from a command's response.

Example

{
  "commands": [{
    "hdr": "713",
    "rax": "77D",
    "cmd": {"22": "2B1B"},
    "freq": 0.25,
    "signals": [{
      "id": "TAYCAN_TIRE_FL_SPD",
      "path": "Movement",
      "fmt": {
        "len": 16,
        "max": 1000,
        "mul": 0.05625,
        "unit": "kilometersPerHour"
      },
      "name": "Front left wheel speed"
    }]
  }]
}
    

How the value is calculated

var value: Double
if sign {
  value = SignedBitReader(response, bix, len)
} else {
  value = UnsignedBitReader(response, bix, len)
}
value = (value * mul / div + add).clamped(to: min...max)
return Measurement(value: value, unit: unit)
    

Required properties

Optional properties


ServicePID

A service PID represents a parameter ID for a specific service.

Examples

{"22": "2B1B"}
{"01": "02"}
    

Two services are currently supported: 01 and 22.

Service Format Example
01
hh 01
22
hhhh 2B1B

Signal

Signals are individual values contained within the response of a Command sent to a vehicle. Most Commands only have one Signal, but Commands can pack any number of signals into a single response.

Example

{
  "commands": [{
    "hdr": "713",
    "rax": "77D",
    "cmd": {"22": "2B1B"},
    "freq": 0.25,
    "signals": [{
      "id": "TAYCAN_TIRE_FL_SPD",
      "path": "Movement",
      "fmt": {
        "len": 16,
        "max": 1000,
        "mul": 0.05625,
        "unit": "kilometersPerHour"
      },
      "name": "Front left wheel speed"
    }]
  }]
}
    

Required properties

Optional properties


Unit

Units define how a signal's value should be interpreted and represented to the user. Units are categorized, and values of the same unit category can be translated to one another. For example, miles and kilometers both belong to the same unit type Length.

If a unit includes a version (e.g. v1.13+), that means the unit was introduced in that version of the Electric Sidecar application. Older app versions will fall back to treating unknown units as a scalar.

Accleration units

Angle units

Electric current units

Electric potential difference units

Energy units

Length units

Mass flow rate units

Normal units

Power units

Pressure units

Revolutions units

Scalar units

Speed units

Temperature units

Time units

Volume units