Calculation translators
A calculation translator derives a new value from fields a device has already reported, and writes the result back alongside them. Converting a temperature to Fahrenheit, turning a distance into a tank volume, or turning an ever-growing meter reading into "how much this month" are all calculation translators.
Like alarm translators they are chained: they run on top of the device's hardware translator and read fields it has already decoded, not raw payloads.
Why use a calculation translator
The value is computed once, on the way in, and then stored on the device like any other field.
That matters more than it sounds. Every dashboard, view, report, rule and export downstream reads the same stored number, so nobody recalculates it and nobody disagrees about it. A monthly kWh figure is waiting on the device the moment it is asked for, rather than being derived from history at query time by whoever needs it.
It also means a derived value is a first-class field, so anything that works on device data works on it. Most usefully, an alarm translator can supervise a calculated field exactly as it supervises a measured one, which is how you alarm on something the sensor never reported.
Totals per time period
These keep rolling day, week, month, quarter and year buckets on the device. When a bucket's window rolls over, that bucket resets and starts again. All of them take a timeZone parameter, because period boundaries are local: midnight and Monday mean different instants in different places.
| Translator | What it computes | Fields produced |
|---|---|---|
calculate-energy-consumption-per-time-period | Energy used so far in the current day, week, month, quarter and year, from a cumulative kWh meter. Feed the result to set-alarm-energy-consumption to catch overspend early | energyConsumptionDay, energyConsumptionWeek, energyConsumptionMonth, energyConsumptionQuarter, energyConsumptionYear |
calculate-counter-delta-per-time-period | How much any monotonically increasing counter has grown so far in the current period. kWh, litres, cycles, anything that only goes up | amounts |
calculate-amount-by-time-period | How much a growing counter accumulated over the last day, week, month, quarter and year | amounts |
calculate-amount-sum-per-time-period | Sums a value from every uplink into the same period buckets, plus a lifetime total. Use it when each report carries an amount rather than a running counter | amounts |
The distinction worth getting right: counter-delta and amount-by-time-period read a counter that only grows, and work out the difference. amount-sum reads a quantity reported each time and adds them up.
People and traffic counting
| Translator | What it computes | Fields produced |
|---|---|---|
calculate-people-count-total | A lifetime in/out total that survives sensor resets. A counter can drop to zero for reasons that have nothing to do with people leaving: a configured daily reset, a network rejoin, a battery change. This adds the increase each uplink, and on a drop adds the new value rather than a negative difference, so the total only ever grows | peopleCountTotalIn, peopleCountTotalOut |
calculate-people-count-daily | A "so far today" count that resets at local midnight | peopleCountDailyIn, peopleCountDailyOut |
calculate-people-count-per-time-period | Rolling day, week, month, quarter and year totals plus a lifetime total, counting continuously | people |
calculate-people-count-during-time-window-per-time-period | The same periods, but counting only inside a daily time window, with an option to skip weekends. For opening hours rather than round the clock | people |
calculate-traffic-counter-total | Lifetime totals for a PMX traffic-counter radar, per speed class and per direction. The traffic equivalent of calculate-people-count-total | countClass0TotalLTR … countClass4TotalRTL |
Unit conversion, scaling and calibration
| Translator | What it computes | Fields produced |
|---|---|---|
calculate-temperature-fahrenheit | Celsius to Fahrenheit, one decimal | temperatureF |
calculate-average-temperature-fahrenheit | The same for an averaged temperature reading | averageTemperatureF |
calculate-scale-by-factor | Multiplies a reading by a fixed factor | scaledValue |
calculate-linear-calibration | Applies a linear calibration, k and m, to a reading. For correcting a sensor with a known offset and slope | arithmeticResult |
calculate-4-20-ma-scaling | Rescales a 4–20 mA current-loop reading onto the sensor's engineering range. 4 mA is the bottom of the range, 20 mA the top, which is how most analog process sensors for pressure, level and flow report | arithmeticResult |
calculate-strips-drip-calibration | Calibration helper for the Sensative Strips Drip | capMin, capMax, calibrationStatus |
Environment
| Translator | What it computes | Fields produced |
|---|---|---|
calculate-dew-point-from-temperature-rh | Dew point from a temperature and relative-humidity pair, using the SMHI approximation. The temperature the air would have to cool to before its moisture condenses: close to the air temperature means condensation, fog or sticky indoor air is likely | dewPointTemperature |
calculate-frost-precipitation | Whether frost is forming on a cold surface, by comparing surface temperature to the dew point of the surrounding air. A surface colder than the dew point pulls moisture out of the air, and below freezing that moisture becomes frost | frostPrecipitation, state |
Tank contents and diagnostics
| Translator | What it computes | Fields produced |
|---|---|---|
calculate-cylinder-fill | Volume of contents and fill level of a cylindrical tank, from a range-finder reading. Handles a tank standing or lying, and a sensor measuring from the ceiling or the floor | volume, fillLevel |
calculate-satellite-snr | Unpacks a 32-bit bestSatellites word into four individual satellite signal-to-noise values, for diagnosing GNSS reception | satelliteSNR1 … satelliteSNR4 |
Decoders with calculation built in
Two entries decode a raw device payload and calculate on the same message, so they are hardware translators rather than chained ones. They are listed here because of what they compute:
| Translator | What it does |
|---|---|
dragino-lht65-dewpoint-calculation | Decodes a Dragino LHT65 uplink and computes dew point from its internal temperature and humidity |
vegapuls-air41-cylinder-calculation | Decodes a Vega Vegapuls Air 41 radar uplink and converts the distance into tank volume and fill level, for silo, tote and buffer-tank monitoring |
Parameters
Calculation translators follow the same convention as the alarm family: most parameters are optional and carry a default, though some - such as the physical dimensions a volume calculation needs - are required, and the input field is resolved automatically unless you point it somewhere specific.
| Parameter | Purpose |
|---|---|
[quantity]Field | Read the source value from a specific field path instead of the automatic default. For example energyField, counterField, temperatureField, peopleInField |
timeZone | Local time zone that decides when day, week, month, quarter and year boundaries fall. Used by every per-period translator |
The geometry and scaling translators take the numbers describing the installation instead: radius, length, isStanding and isDistanceFromCeiling for a tank; multiplyerK and additionM for a linear calibration; min_mA_value and max_measured_range for a current loop.
Chaining
Calculation translators are most useful in front of another translator. Three chains worth knowing:
- Energy budget. Meter →
calculate-energy-consumption-per-time-period→set-alarm-energy-consumption. The meter reports a lifetime figure, the calculator turns it into this month's usage, and the alarm fires when the month exceeds the contracted allowance. - Frost warning. Temperature and humidity sensor →
calculate-dew-point-from-temperature-rh→calculate-frost-precipitation→set-alarm-frost-precipitation. Each step adds one value, and the alarm at the end needs no thresholds because the calculator has already reached a verdict. - Reliable people counts. People counter →
calculate-people-count-total→calculate-people-count-per-time-period. The first makes the count survive the sensor's resets, the second buckets it into periods.
For the alarms at the end of these chains, see Alarm translators. For the full A–Z index of every translator, see the translators overview.