×
 

Applying formulas

A conversion formula is a mathematical expression applied to the data received from a sensor.
Why use a formula:
• To correct sensor readings — for example, a formula allows you to fix inaccuracies in sensor data
• To convert raw sensor data into real physical values. For example, if a sensor outputs numbers from 0 to 1000, the formula can transform them into actual liters of fuel in a tank
• To convert units of measurement, for example, kilometers to miles or liters to gallons
• To combine data — for example, a formula can use values from different sensors to calculate new indicators
In the sensor settings window, the formula is applied in a special Conversion formula field.
Applying formulas
11.
The formula is applied to data immediately after it is received from the sensor, before using the calibration table.
The formula must start with one of the following signs:
• arithmetic signs: +, -, *, /
• equals sign: =
You can use in a formula:
• mathematical operations: addition (+), subtraction (-), multiplication (*), division (/)
• parentheses ( ) to specify the order of operations
 

Simple formulas

Used for simple operations such as multiplication, division, addition, and subtraction. The raw sensor value is automatically substituted into the formula.
Example of applying a formula
Suppose we have a battery charge sensor that transmits a value in millivolts. In the raw points, we see: Vsource = 9337.
To display the usual sensor value in volts, the raw value must be divided by 1000. In the sensor settings window, in the Conversion formula field, we write: /1000.
The final sensor value will be calculated by the formula Vbattery/1000:
1. The system takes the current raw value from the sensor
2. Divides this value by 1000
3. The result becomes the new sensor value
The final battery value in volts will be displayed in the object tooltip — 9.33V.

Examples of simple formulas

 Formula
  Result
   *10
  Multiply the raw value by 10
 /1000
  Divide the raw value by 1000
   /25.5+7
  Divide by 25.5 and add 7
  /100+(7*3-2)*4
  More complex example using parentheses
Decimal fractions in formulas must use a dot, not a comma. For example: 25.4, 1.75

Variables in a formula

Formulas can use data from sensor fields and standard variables.
All values used in a formula must be wrapped in %%.
Standard variables that can be used in formulas:
%S% — speed
%A% — altitude
%D% — direction
%P% or %satsinview% — number of satellites
%ts% — current packet timestamp
%ts1% — previous packet timestamp
%value% — current sensor value
Timestamps are in Unix timestamp format (seconds since Jan 1, 1970).
Other values can be taken directly from raw data packet field names. For example:
%Vbattery% — battery charge value
%GSM% — GSM signal strength
%HDOP% — horizontal dilution of precision
Simply wrap the parameter name in %%, and it will be replaced by the corresponding value during calculation.

Examples of formulas with variables

  Formula
  Result
   *%GSM%
  Multiply raw value by GSM field data
   /%HDOP%
  Divide raw value by HDOP field data
   %ts1%-%ts%
  Get time difference between current and previous packet
   %ts%/86400
  Convert timestamp from seconds to days
 

Complex formulas

Complex formulas always begin with the = sign.
In these formulas, the raw sensor value is not automatically used. If you need it, you must include it explicitly as %value%.
This type of formula allows more advanced operations, including the use of variables, parentheses, and mathematical functions.

Examples of complex formulas

   Formula
  Result
   =%value%*2+10
  Multiply raw value by 2 and add 10
 =%S%*3.6+%value%
  Convert speed to km/h and add raw sensor value
   =(%DIN1%+%DIN2%)/%value%
  Divide sum of digital inputs by raw sensor value
  =7/%value%
  Divide 7 by raw sensor value
 

Conditional operators

Conditional operators are a way to set up decision logic in a formula. They allow the formula to return different values depending on whether a certain condition is true or false. This is similar to saying: “If the condition is true, do one thing, otherwise do another.”
A conditional operator is written like this:
condition ? value_if_true : value_if_false
This expression can be explained as follows:
  • condition — the expression being checked, for example, temperature greater than 30
  • value_if_true — the value returned if the condition is true
  • value_if_false — the value returned if the condition is false

Comparison operators

You can use the following operators:
 Operator
  Meaning
  Description
   ==
  equal    
  checks exact equality
   !=
  !=    
  checks inequality
   >
  greater
  left value greater than right
   <
  less
  left value less than right
   >=
  greater or equal
  left ≥ right
  <=
  less or equal
  left ≤ right
  &&
  and
  all conditions must be true
   ||
  or
  at least one condition must be true

Example 1

Let’s say we have a digital input sensor field DIN1, and we want to set a condition:
  • If DIN1 equals 1, the result will be 22
  • If DIN1 does not equal 1, the result will be 33
The formula will look like this:
=(%DIN1% == 1) ? 22 : 33
The system checks the condition: %DIN1% == 1 (whether the value of DIN1 equals 1).
  • If the condition is true, it returns 22.
  • If the condition is false, it returns 33.

    Example 2

Let’s say we have a temperature sensor field temp, and we want to set a condition:
  • If the temperature is greater than 30, the result will be temperature * 10
  • If the temperature is less than or equal to 30, the result will be temperature * 20
The formula will look like this:
=(%temp% > 30) ? %temp% * 10 : %temp% * 20
The system checks the condition: %temp% > 30 (whether the temperature is greater than 30).
  • If the condition is true, it returns temperature × 10.
  • If the condition is false, it returns temperature × 20.
     

Example 3

Let’s say we have a temperature sensor field temp and a humidity sensor field humidity, and we want to set the following condition:
  • If the temperature is greater than 25 AND the humidity is less than 60%, the result will be 100
  • Otherwise, the result will be 50
The formula will look like this:
=(%temp% > 25 && %humidity% < 60) ? 100 : 50
Here:
  • %temp% > 25— the first condition (temperature greater than 25)
  • %humidity% < 60— the second condition (humidity less than 60%)
  • The operator && means both conditions must be true.
The system checks the conditions, and:
  • If both conditions are true, it returns 100
  • If at least one condition is false, it returns 50
 

PHP functions

PHP functions are built-in tools of the PHP programming language for processing, transforming, and formatting data.
They can be used directly in formulas to perform advanced transformations.
Usage steps:
  • Write the function name in the formula
2. Put the value(s) you want to process in parentheses
3. The system automatically processes the value and returns the result
Example: =round(45.78) → 46
 

Common PHP functions used in formulas

   Function
  Description
   Example
   substr
   Extracts part of a string    
   =substr('%FIELD%', 1, 2) → returns 2 characters starting from position 1
   round
  Rounds a number
  =round(%AIN1%/1000)
   hexdec
  Converts hex to decimal
  =hexdec('%Param%'), if Param = 0A, then the function will return the value 10
   dechex
  Converts a decimal number to hexadecimal
  =dechex('%Param%'), if Param = 255, then the function will convert 255 into 'FF'
   decbin
  Converts a decimal number to binary
  =decbin('%Param%'), if Param = 10, the function will return 1010
   hex2bin
  Converts a hexadecimal string into binary data
  =hex2bin ('%Param%'), if Param = 4142, then the function will return the binary representation 'AB'
   strrev
  Reverses a string
=strrev('%value%'), if value = 0123d848010000e5, the function will convert it to 5e000001048d3210
   bytesrev
  Reverses hexadecimal bytes
  =bytesrev('%value%'), if value = 0123d848010000e5, the function will convert it to e500000148d82301
   explode
 
 Splits a string into parts using a specified delimiter and returns an array of strings
 
=explode(',','%value%')[2]
Suppose the sensor sends a string of values separated by commas:
90.5,3450,112,43,215
The formula =explode(',','%value%')[2] takes the sensor readings, splits them into an array:
'90.5', '3450', '112', '43', '215',
and then extracts the element with index 2 — '112'.
  • A string array is a list of individual strings, numbered from zero.
  • ','is the delimiter, in this case a comma. Splitting happens at this symbol.
  • '%value%'is the string that needs to be split.
  • [2]— square brackets are used to access an element of the array. [2] means “give me the third element”, since numbering starts at 0.
   max
Compares several values and returns the largest one
  =max('%value%', 90), if value = 85, the function will return 90
   min
  Returns the smallest value
  =min('%value%', 90), if value = 85, the function will return 85
   abs
  Returns the absolute value of a number
  =abs('%value%'), if value = -15, the function will return 15
   str_replace
  Replaces some characters or words with others
 
  • search — what to look for
  • replace — what to replace with
  • subject — where to look (the string)
Example: if you need to replace commas with dots in numbers:
=str_replace(",", ".",'%value%')
If value = 1,234,567, the function will return 1.234.567
  sqrt
  Calculates the square root
  =sqrt('%value%'), if value = 25, the function will return 5
  pow
  Raises a number to a power
  =pow('%value%', 3), if value = 2, the function will return 8 (that is, 2³)
  sin
  Calculates the sine of an angle (in radians)
  =sin('%value%'), if value = 1.57, the result ≈ 1
  cos
  Calculates the cosine of an angle
 (in radians)
  =cos('%value%'), if value = 0, the result will be 1
  asin
  Calculates the arcsine (in radians)
  =asin('%value%'), if value = 1, the function will return 1.57
  acos
  Calculates the arccosine (in radians)
  =acos('%value%'), if value = 0, the function will return 1.57
  number_format
  Formats a number with separators
  =number_format(1234.56, 2, ',', ' ') , the function will return 1 234,56
   time
 Returns the current time in UNIX format — the number of seconds since January 1, 1970
   =time('2023-12-20 12:00:00')
   array_sum
  Adds up all numbers in an array
   =array_sum([1,2,3,4]) — the function returns 10
   pack
  Packs data into binary format
   =pack('H*', '4142') — packs into binary data 'AB'
   unpack
  Unpacks binary data
   =unpack('H*', 'AB')[1] — returns '4142'
 

Examples of complex transformations

  Description
   Example
Unsigned number to signed number conversion
=((%BLE_T1%>3000)?((%BLE_T1%-65535)/100):(%BLE_T1%/100)) 
  • If the number is greater than 3000 — subtract 65535 from it and divide by 100
  • If it is less than or equal to 3000 — divide by 100
    This formula is often used for temperature sensors, where negative values are encoded as large positive numbers.
  Byte sequence conversion (little endian to big endian)
 =strtoupper(substr(unpack('H*',strrev(hex2bin(%value%)))[1],2,12))
Example: 1500000124286b01 → 6B2824010000
Step by step:
  • hex2bin(%value%) — converts a hex string into binary data
  • strrev(...) — reverses the bytes
  • unpack('H*', ...) — converts back into hex
  • substr(..., 2, 12) — extracts the required part of the string
  • strtoupper(...) — converts the result to uppercase

Division by zero

When a formula involves division, be careful with the divisor — the number you are dividing by.
If the divisor equals zero, an error will occur because dividing by zero is mathematically impossible.
For example, the formula:
=1000/%DIN1%
will cause an error if the value of sensor DIN1 is 0 or undefined.
In this case, use a conditional operator to check the divisor:
=(%DIN1%==0) ? 0 : 1000/%DIN1%
The system will check the condition: %DIN1% == 0 (whether the value of DIN1 equals zero).
If the condition is true, the result will be 0.
If the condition is false, the system will perform the division 1000 / DIN1 value.
 

How to test a formula

When you apply a formula, make sure it correctly transforms the data.
You can test the formula using the Test button:
Applying formulas
  • Click the Test button in the Formula field
1

Test button

1.
2. The system will display values that you can use to test the formula defined in the handler. You can select predefined values or enter your own.
3. After that, click Test again, and the system will show the result of applying the formula: whether it’s correct or not.
 

Where else formulas are used

In PILOT, formulas can be used not only for processing sensor data. You can also apply formulas in the Object card or when working with the Notifications module.
In all cases, the principle remains the same — the same formula writing rules and mathematical operations apply.