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