Extended Parameters
How to extend 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 Sidecar
In addition to supporting many of the industry standard OBD-II PIDs specified in SAE J1979, Sidecar pulls extended PIDs from the OBDb, github.com/OBDb.
Every vehicle make and model has its own GitHub repository in the OBDb GitHub 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@clutch.engineering or open an issue.
When you connect a scanner to your car, 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 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/OBDb.
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.
pri | String | ATCPhh On 29-bit CAN-ID networks, this property can be used to set the top 5 bits of the CAN header. If not provided, then the default priority bits of 18 will be used.
tst | String | ATTAhh The tester (ie. scan tool) address that is used in the headers, periodic messages, filters, etc. If not provided, then the default tester address of F1 will be used.
tmo | String | ATSThh The timeout, expressed as a hexadecimal value in increments of 4 msec. The ELM327 waits a preset time for a response before it can declare that there was NO DATA received from the vehicle. The same timer setting is also used after a response has been received, while waiting to see if any more are coming. This property allows this timeout period to be adjusted. If no timeout value is provided, then the default of 32 (~200ms) will be used.
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 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, as a percentage.
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.starterBatteryVoltage | Volts The starter battery’s voltage.distanceSinceDTCsCleared | Length How far you’ve traveled since resetting your diagnostic trouble codes.
#
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.
nullmin | Double An optional null value. Any response equal to or less than this value will be treated as a null value.
nullmax | Double An optional null value. Any response equal to or greater than this value will be treated as a null value.
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 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 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.
Concentration mass
gramsPerLiter Concentration mass in grams per liter.milligramsPerDeciliter Concentration mass in milligrams per decileter.
Electric current units
kiloamps Current in kiloamps.amps Current in amperes.milliamps Current in milliamps.
Electric charge units
coulombs Electric charge in coulombs.kiloampereHours Electric charge in kiloampere-hours.ampereHours Electric charge in ampere-hours.milliampereHours Electric charge in milliampere-hours.
Electric efficiency units
kilowattHoursPer100Kilometers Electric efficiency in kilowatt hours per 100 kilometers.kilowattHoursPer100Miles Electric efficiency in kilowatt hours per 100 miles.milesPerKilowattHour Electric efficiency in miles per kilowatt hour.
Electric resistance units
megaohms Electric resistance in megaohms.kiloohms Electric resistance in kiloohms.ohms Electric resistance in ohms.milliohms Electric resistance in milliohms.microohms Electric resistance in microohms.
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.
Energy units
kilowattHours Kilowatt-hours.kiljoules Kilojoules.joules Joules.
Frequency units
terahertz Frequency measured in terahertz.gigahertz Frequency measured in gigahertz.megahertz Frequency measured in megahertz.kilohertz Frequency measured in kilohertz.hertz Frequency measured in hertz.millihertz Frequency measured in millihertz.microhertz Frequency measured in microhertz.nanohertz Frequency measured in nanohertz.framesPerSecond Frequency measured in frames per second.
Length units
millimeters Distance in millimeters.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.
Mass per stroke units
milligramsPerStroke Mass per engine stroke.
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.