User-Defined PIDs Help

When creating a user-defined PID, you define the data that is sent to the vehicle. This is an advanced feature that requires knowledge of the OBD2 standard, and you are fully responsible for any and all consequences.


Units

This section defines the unit names and conversion from Metric to English units. User-defined PIDs are always evaluated in Metric units, and you can provide a scale factor and offset to convert the value to English units.

Metric Units

Use this value to set the Metric unit name.

English Units

Use this value to set the English unit name.

Metric to English Scale Factor/Offset

User-defined PIDs are always evaluated in Metric units. Use the Metric to English Scale Factor and Metric to English Offset to define the conversion from Metric to English units. The Scale Factor and Offset are used as follows:

English Value = (Metric Value * Scale Factor) + Offset

For example, if you have units for temperature of Celsius and Fahrenheit, the Metric to English Scale Factor would be 1.8 and Metric to English Offset would be 32.


Min/Max

Use the Min and Max values to set the expected range of this parameter.

Use the Number of Decimals to set the number of decimals places to use when displaying this parameter.


OBD Information

Module/Header

Use this value to configure the vehicle module to which you want to direct the request. You can enter an acronym such as ECM, TCM, ABS, SRS, or ALL, or you can enter the address of the module (e.g. 7E0). When you enter ECM, TCM, ABS, or SRS, physical addressing is used and the address of the module is determined based on typical addressing used by vehicle manufacturers. However, not all manufacturers address modules the same way, so this is not guaranteed to address the correct module. When you enter ALL, functional addressing is used, which sends the request to all modules that respond to functional addressed requests. Typically, only OBD2 compliant modules will respond to a functional request, and they will only respond when the OBD mode is one of the legislated OBD2 modes (e.g. Mode 01).

When you enter a numeric value, you are specifying the module address. The actual header that is used might include other bytes. For example, on 29-bit CAN, if you enter a value of 10, the actual header bytes will be DA10F1. If you want to specify the exact header bytes that are used, prefix the value with the @ symbol. For example, on 29-bit CAN, if you enter a value of @DA10F0, the actual header bytes used will be DA10F0. You should enter three bytes when using the @ symbol. If you enter one or two bytes when using the @ symbol, the upper bytes of the header will be set to zero. Otherwise, if not using the @ symbol, you must only enter one byte for all protocols except 11-bit CAN or two bytes for 11-bit CAN.

11-bit CAN Extended Address (Hex)

Use this value to set an extended address for 11-bit CAN. When set to a non-zero value, this value is used along with the Module/Header to define the full address of the module. Extended addressing is only used when accessing certain non-OBD2 compliant modules that are typically located behind a gateway module. Due to the additional latency involved in accessing modules with extended addressing, you might have to increase the ECU Response Wait Time and disable Adaptive Timing on the Advanced preferences page.

11-bit CAN Response Address (Hex)

Use this value to set a non-default response address for 11-bit CAN. Normally, the 11-bit CAN response address equals the module address plus 8. However, some non-OBD2 compliant modules use a response address that does not follow that convention. Set this value to zero or blank to use the default response address. This value only applies to the 11-bit CAN protocol.

OBD Mode

Use this value to set the mode byte that is sent with the request. This value is a single byte in hexadecimal format. Typical values are 01, 21 and 22.

PID Number

Use this value to set the number of the PID that is sent with the request. This value can be one or more bytes in hexadecimal format. For mode 01 PIDs, this value should be a single byte (e.g. 04). For mode 22 PIDs, this value is typically two bytes (e.g. 0200).

Priority

Use this value to configure how often the PID is read from the vehicle relative to other PIDs. PIDs whose value changes often can be given a high priority, and PIDs whose value does not change very often can be given a lower priority.


Equation

The equation is used to convert the raw data from the vehicle into a numeric value. The equation can also be used to combine other SAE PIDs by using the readSaePid function. The format of the equation is described in detail below.

OBD Data Tokens

OBD data tokens are reserved letters that represent the index into the data bytes returned from the vehicle. Valid values are A-Z, AA-IV, which represents data indexes 0–255 of the data bytes returned from the vehicle. For example, the token A will be replaced by the first byte of data returned from the vehicle. Token B will be replaced with the second byte of data returned from the vehicle, and so on.

Mathematical Operators

The following mathematical operators are available. Operators with a higher precedence value will be evaluated before operators with a lower precedence. Parentheses can be used to group operations.

Operator Name Prec. Example
^ Exponent 4 2 ^ 3 = 8
* Multiply 3 3 * 5 = 15
/ Divide 3 10 / 2 = 5
+ Add 2 2 + 7 = 9
- Subtract 2 8 – 4 = 4
& Bitwise And 1

7 & 3 = 3

11 & 6 = 2

: Get bit 1

5:2 = 1 (bit 2 set)

5:1 = 0 (bit 1 not set)

5:0 = 1 (bit 0 set)

Data Types

All data types are implicit and are not declared. Double floating-point calculations are performed when evaluating each equation and the result of each equation is always a double. Functions (as described below) have implicit data types.

Functions

The following functions are built into the language and can be used to manipulate data. Also, functions are available to access other PIDs. Note that function names are currently case in-sensitive. The implicit data types for return values and arguments are listed in brackets for reference only (e.g. [double], [int16], etc.). You should not include the data types in your equations.

Function Description Example
[double] int16([int16] value) Casts the input value to a signed 16-bit integer and returns the result

int16(4080) = 4080

int16(65535) = -1

[double] int32([int32] value) Casts the input value to a signed 32-bit integer and returns the result

int32(65535) = 65535

int32(4294967295) = -1

[double] signed([byte] value) Casts the input value to a signed 8-bit integer and returns the result

signed(10) = 10

signed(255) = -1

[double] abs([double] value) Returns the absolute value

abs(10) = 10

abs(-10) = 10

[double] combine([byte] b0, [byte] b1) Combines two bytes into a single double value

combine(A, B) = A * 256 + B

[double] combine([byte] b0, [byte] b1, [byte] b2) Combines three bytes into a single double value

combine(A, B, C) = A * 256^2 + B * 256 + C

[double] combine([byte] b0, [byte] b1, [byte] b2, [byte] b3) Combines four bytes into a single double value

combine(A, B, C, D) = A * 256^3 + B * 256^2 + C * 256 + D

[double] float32([byte] b0, [byte] b1, [byte] b2, [byte] b3) Converts four bytes to a single-precision IEEE 754 floating point value

float32(68, 122, 00, 00) = 1000

[double] readSaePid([string] pidId) Reads the value of another SAE PID based on its unique ID. Used to create PIDs that are combinations of other PIDs. See note (1)

readSaePid(0C) = Engine RPM

readSaePid(14.1) = O2 Sensor 1 Short Term Fuel Trim

[double] readUserPid([string] "pidId") Reads the value of another user-defined PID based on its unique ID. Used to create PIDs that are combinations of other PIDs. See note (2)

readUserPid("pidId") = Metric Value

(1) The pidId argument of the readSaePid function must match the SAE PID number in hexadecimal format. For example, the pidId for engine RPM is 0C. Some SAE PIDs return multiple values. For example, SAE PID 0x14 returns O2 voltage and short-term fuel trim. Since O2 voltage is the first part of the response, its pidId is 14. Since short-term fuel trim is the second part of the response, its pidId is 14.1. The value returned is always in Metric units. You should write your equations to evaluate to Metric units and use the offset and scale factor to define English conversions.

(2) The pidId argument of the readUserPid function must match the ID of the user-defined PID that's displayed in the information section. Enclose the ID in quotes. A unique ID is automatically created when you create a new user-defined PID and cannot be changed. The value returned is always in Metric units. You should write your equations to evaluate to Metric units and use the offset and scale factor to define English conversions.

Referencing other User-Defined PIDs

You can reference other user-defined PIDs in a PID equation with the readUserPid function that's described in the previous section.

You can also reference other user-defined PIDs in a PID equation by specifying the PID mode and number in brackets. For example, suppose you have an existing user-defined PID using mode 22 and PID number 1234. To reference that PID from another PID equation, you would enter [221234] in the equation. If you have multiple user-defined PIDs with the same mode and PID number, the first matching PID will be used. In that case, you should use the readUserPid function to ensure you are referencing the correct PID.

As with the readSaePid function, the value returned for the other PID will be in Metric units.


Importing From CSV File

User-defined PIDs can be imported from a CSV file that contains the PID definitions. Press Menu > Import from file to import PIDs from a CSV file. The CSV file must follow the format specified below, which includes a header row and a row for each PID definition.

Header Row

The first row in the file must contain the column names listed below. Column names listed in brackets ([]) are optional. Column names separated with a '|' indicate that either column name can be specified, but not both. The order of the columns does not matter.

Name|Description, [ShortName], ModeAndPID, Min, Max, Units|[MetricUnits,EnglishUnits], Formula|Equation, Header, [MetricToEnglishScaleFactor], [MetricToEnglishOffset], [Priority], [NumberOfDecimalPlaces], [CANExtendedAddress], [EcuResponseAddressCAN]

Column Name Required Example Notes
Name | Description Yes Vehicle Speed Sets the description of the PID. If ShortName is not specified, also sets the name of the PID.
ShortName No Speed Sets the name of the PID
ModeAndPID Yes 221234
Min Yes 0
Max Yes 100
Units Yes* km/h Only required if MetricUnits and EnglishUnits are not specified
MetricUnits No* km/h Required if Units is not specified
EnglishUnits No* MPH Required if Units is not specified
Formula | Equation Yes A + 50 Specify Formula or Equation
Header Yes 7E0
MetricToEnglishScaleFactor No 1.8
MetricToEnglishOffset No 32
Priority No Medium See the list of valid priorities below
NumberOfDecimalPlaces No 3 Valid values are 0 to 6
CANExtendedAddress No A2 Values are specified in hex
EcuResponseAddressCAN No 720 Values are specified in hex

For the units column, you can specify one column with the name "Units" or you can specify two columns named "MetricUnits" and "EnglishUnits". If you specify one "Units" column, the value will be used for both Metric and English units.

You can use quotes on any column name or value, and you must use quotes if any column value includes a comma. All numeric values must use a decimal point ('.') for decimal values (decimal commas are not supported).

Valid priority values are: VeryLow, Low, Medium, MediumHigh, and High

Sample File

Name ModeAndPID Min Max Units Equation Header
Vehicle speed 010D 0 255 km/h A 7E0
Engine RPM 010C 0 16384 RPM (256 * A + B) / 4 7E0