What is Gauge Math?
Gauge Math are optional math equations which may be used to manipulate input values for display in a gauge. To edit Gauge Math for a specific gauge, select the gauge and go to Look&Feel > Special > Gauge Math. Click/Tap on the white box and enter your equation. By default – if the field is left empty – this will simply return the input value.
The same syntax is also used for the Set value (formula) action, which may be used to calculate values upon trigger activation or a button press. Gauge Math, on the other hand, is performed every time the input value the gauge is linked to is updated.
All math equations must start with one equals sign =, otherwise the input is considered invalid and the operation will not be performed. This is the same behavior as in spreadsheet applications like Excel.
Which values/parameters can we use?
Usable parameters are:
- the target ID/value already assigned to the gauge or action. Use
Vto manipulate this value in math equations. Example: if ‘Gauge Math’ is set to=2*V, the gauge will always show double the actual input value. - all other target IDs, prefixed with
ID. A list of all available target IDs can be found here. Example: Target ID for ‘Vehicle Speed’ isID64. - custom values defined in the XML file associated with your dashboard or OBD2/CAN connection, circumfixed with apostrophes
''. E.g. ifmy_valueis defined in the XML file, use'my_value'to reference it in math equations. - any number as a static value, including the constants π (
PI) and e (E).
Notes:
(1) Certain target IDs, like “Weather: Description (Net)”, or navigation instructions, have pre-defined text outputs. It is best to not manipulate these values using Gauge Math to avoid unintended behavior of gauges using these values.
(2) Target IDs with Boolean values will be handled as integers in Gauge Math: 0 = off/false and 1 = on/true.
Which operations can we perform?
Note: the list of operators below may be incomplete, as I add all operators beyond the basic ones by trial and error, or referenced from previous forum posts. Feel free to add to this in the comments as well.
| Operation | Description | Parameters | Syntax |
|---|---|---|---|
| Addition | Add two values | 2 | A+B |
| Subtraction | Subtract value B from value A | 2 | A-B |
| Multiplication | Multiply two values | 2 | A*B |
| Division | Divide value A by value B | 2 | A/B |
| Remainder | Subtract B from A until B>A, then return the remainder of A. (Modulo, A mod B) | 2 | A%B |
| Power | Raise A to the Bth power | 2 | A^B = POW(A,B) |
| Square root | Return square root of A | 1 | SQRT(A) = A^0.5 |
| Natural logarithm | Return the natural logarithm (base e) of A | 1 | LN(A) |
| Decimal logarithm | Return the logarithm (base 10) of A | 1 | LOG(A) |
| Natural exponential | Return e to the power of A | 1 | EXP(A) = E^A = POW(E,A) |
| Sine | Return sine of A | 1 | SIN(A) |
| Cosine | Return cosine of A | 1 | COS(A) |
| Tangent | Return tangent of A | 1 | TAN(A) |
| Inverse Sine (arcsine) | Return arcsin of A | 1 | ASIN(A) |
| Inverse Cosine (arccosine) | Return arccos of A | 1 | ACOS(A) |
| Inverse Tangent (arctangent) | Return arctan of A | 1 | ATAN(A) |
| Hyperbolic sine | Return sinh of A | 1 | SINH(A) |
| Hyperbolic cosine | Return cosh of A | 1 | COSH(A) |
| Hyperbolic tangent | Return tanh of A | 1 | TANH(A) |
| Round up (ceiling) | Round A up to the nearest integer | 1 | CEIL(A) |
| Round down (floor) | Round A down to the nearest integer | 1 | FLOOR(A) |
| Absolute value | Return A as an unsigned value | 1 | ABS(A) |
| Maximum | Compare values A and B, return the larger one | 2 | MAX(A,B) |
| Minimum | Compare values A and B, return the smaller one | 2 | MIN(A,B) |
| Pi | Return π = 3.14159… | 0 | PI |
| Euler’s number | Return e = 2.71828… | 0 | E |
Notes
(1) other trigonometric functions:
- Cotangent: cot(A) = 1/tan(A)
- Secant: sec(A) = 1/cos(A)
- Cosecant: csc(A) = 1/sin(A)
(2) Roots other than the square root can be calculated using powers, as n√x^m = x^(m/n)
What about invalid results, i.e. dividing by zero?
If an equation returns an invalid value, i.e. one which cannot be expressed as a real number, the value will be set to –2,147,483,648 (the lowest possible signed 32-bit integer). This behavior will ignore limits set in ‘Input & Values’ and artificial limits set by triggers. I don’t know if this is intentional, but it does serve a purpose as an error indicator.
Invalid values include:
- divisions by zero, including:
- tan(x) when x is an odd multiple of π/2
- cot(x) when tan(x) = 0
- sec(x) when cos(x) = 0
- csc(x) when sin(x) = 0
- coth(0) = 1/tanh(0) = 1/0
- ln(0) and log(0)
- 0 to the power of 0
- complex numbers (all numbers a + b·i where b ≠ 0; i = √(–1))
- infinity
- text
