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:
{
"diagnosticLevel": String?,
"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
commands | [Command] | Required Array of OBD-II commands that can be sent to this vehicle.
diagnosticLevel | String | Optional The one-byte diagnostic level to use for this vehicle. Written in hex.
signalGroups | [SignalGroup] | Optional Array of signal groups that can aggregate various signals together.
#
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
hdr | String | ATSHhhh The command’s 11-bit header, expressed as 3 hexadecimal characters.
cmd | ServicePID The service and PID that should be sent.
freq | Number The maximum frequency at which this command should be sent, in seconds.
signals | [Signal] The collection of signals that this command returns.
Optional properties
rax | String | ATCRAhhh The command’s 11-bit receive address, expressed as 3 hexadecimal characters. If not provided, then the command will attempt to guess the receive address based on the response.
eax | String | ATCEAhh An extended address byte to be prefixed to the command’s CAN messages, expressed as 2 hexadecimal characters. Some vehicle protocols (e.g. BMW) require this.
fcm1 | Boolean Some parameters only respond with the first frame when using the default flow control mode, 0. Setting this property to true enables flow control mode 1, requesting that all frames be returned together. If not provided, false is assumed and flow control mode 0 will be used. When enabled, the following configuration will be set prior to invoking the command:
ATFCSH7E0 ATFCSD300000 ATFCSM1
#
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
fuelTankLevel | Normal How full the vehicle’s gas tank is.
isCharging | Enum Is the vehicle charging? Must either be an enumeration mapped to a value with a prefix of “CHARGING”, or a scalar unit where a non-zero value means the vehicle is charging.
odometer | Length The total distance the vehicle has traveled.electricRange | Length The distance the vehicle can travel on electricity alone.fuelRange | Length The distance the vehicle can travel on fuel.
pluggedIn | Enum Is the vehicle plugged in? Must either be an enumeration mapped to a value with a prefix of “PLUGGED”, or a scalar unit where a non-zero value means the vehicle is plugged in. 
speed | Speed How fast the vehicle is moving.
stateOfCharge | Normal How full the vehicle’s battery is.
stateOfHealth | Normal The health of the vehicle’s high voltage battery pack.
frontLeftTirePressure | Pressure The front left tire pressure.frontRightTirePressure | Pressure The front right tire pressure.rearLeftTirePressure | Pressure The rear left tire pressure.rearRightTirePressure | Pressure The rear right tire pressure.
#
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
len | Int The number of bits to decode from the response, starting from the bit offset (bix).
max | Double The maximum value this signal can have.
unit | Unit The unit this value should be interpreted as.
Optional properties
bix | Int The bit offset to start reading the value from. Defaults to 0.
blsb | Boolean Whether to swap the byte order prior to reading bits. E.g. a 16 bit value read from offset 8 of 0x012345 in blsb format would be passed to the bit decoder as 0x4523. Defaults to false.
sign | Boolean Whether to treat the bit values as a signed, twos-complement integer. Defaults to false.
min | Double The minimum value this signal can have. Defaults to 0.
add | Double Added to the extracted numerical value. Defaults to 0.
mul | Double The extracted numerical value is multiplied by this value. Defaults to 1.
div | Double The extracted numerical value is divided by this value. Defaults to 1.
omin | Double The optimal minimum value, expressed in the same unit as the value. If not provided, no optimal minimum value will be shown.
omax | Double The optimal maximum value, expressed in the same unit as the value. If not provided, no optimal maximum value will be shown.
oval | Double The optimal value, expressed in the same unit as the value. If not provided, no optimal value will be shown.
#
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
id | String The signal’s globally unique identifier.
name | String The signal’s human-readable name. Should be short and descriptive.
fmt | Format How to interpret the signal’s value from the command response.
Optional properties
path | String The navigation path for the signal in Electric Sidecar’s parameters page. If not provided, the signal’s id property will be used as the navigation path instead.
description | String A long form description of the signal’s purpose and how it should be interpreted.
hidden | Boolean If true, hides the signal from the user interface. Default value is false if not provided.
suggestedMetric | Connectable The user interface value that this signal should update.
#
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
gravity Acceleration as a g-force.
Angle units
degrees Angle in degrees.radians Angle in radians.
Electric current units
kiloamps Current in kiloamps.amps Current in amperes.milliamps Current in milliamps.
Electric potential difference units
kilovolts Voltage measured in kilovolts.volts Voltage measured in volts.millivolts Voltage measured in millivolts.
Energy units
kilowattHours Kilowatt-hours.kiljoules Kilojoules.joules Joules.
Length units
centimeters Distance in centimeters.meters Distance in meters.kilometers Distance in kilometers.miles Distance in miles.feet Distance in feet.inches Distance in inches.
Mass flow rate units
gramsPerSecond Mass flow rate in grams per second.kilogramsPerHour Mass flow rate in kilograms per hour.
Normal units
percent A percentage, typically between 0-100%.normal A normal, typically between 0.0-1.0.
Power units
kilowatts Kilowatts.watts Kilowatts.milliwatts Milliwatts.
Pressure units
bars Pressure in bar.psi Pound-force per square inch.kilopascal Pressure in kilopascal.
Revolutions units
rpm Revolutions per minute.
Scalar units
scalar An as-is numerical value.ascii The extracted bytes will be formatted as an ASCII string. Scaling values will be ignored.hex An as-is numerical value, formatted in hexadecimal. Scaling values will be ignored.offon 0 = “off”, 1 = “on”noyes 0 = “no”, 1 = “yes”yesno 0 = “yes”, 1 = “no”.unknown Treated as an as-is numerical value.
Speed units
metersPerSecond Speed in meters per second.kilometersPerHour Speed in kilometers per hour.milesPerHour Speed in miles per hour.
Temperature units
celsius Temperature in degrees celsius.fahrenheit Temperature in degrees fahrenheit.kelvin Temperature in degrees kelvin.
Time units
seconds Time, measured in seconds.minutes Time, measured in minutes.hours Time, measured in hours.
Torque units
newtonMeters Newton-meters.poundFoot Pound-foot.inchPound Inch-pound.
Volume units
liters Volume in liters.gallons Volume in gallons.