Gauge Math and Formula Reference

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’ is ID64.
  • custom values defined in the XML file associated with your dashboard or OBD2/CAN connection, circumfixed with apostrophes ''. E.g. if my_value is 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

I will add to this whenever I have time and find something new. Please leave corrections and suggestions in the comments below.

3 Likes

Thank you so much for this. This has been requested long time ago, and I never found time to do it.

Too bad there are no string functions. Like concatenation, for example.
Isn’t it possible to include this kind of thing?

This a question for Realdashdev, not for Frongus of course.

Great thanks frongus !!!

… and great thanks too to Realdashdev for sure !!! :slight_smile:

Ps: Which programming language is RealDash written in? This would help documenting more syntax regarding math functions.

99% C++, 1% some other platform specific stuff (Java,Kotlin,ObjC etc.)