A calibration table converts the raw number a sensor sends into a value people can use. A fuel probe, for example, reports 0 to 4000 counts, and the tank holds 0 to 300 litres. You give the table a few measured pairs, such as "at 2000 counts the tank holds 148 litres". The app then converts every reading that arrives.
¶ When to use one
- The relation between reading and value is not a straight line. Most fuel tanks are wider in the middle than at the top and bottom, so equal steps of the probe do not mean equal litres.
- You have a strapping chart, a sensor datasheet or your own measurements, as pairs of reading and value.
- You want to discard impossible readings, such as a temperature probe that reports -200 °C when its cable breaks. The table's bounds do that, even without any points.
For a straight line with one factor or offset, an expression is enough: {ext_volt} / 1000. See Sensor expressions.
¶ Measured points and segments
You enter the table as Measured points: each point is a raw reading (X) and the value it means (Y). Generate coefficients turns each pair of neighbouring points into one straight segment, written as Y = aX + b:
- X is where the segment starts.
- A is the slope: how much the value grows for each step of the reading.
- B is the value the line would have at a reading of 0.
With the points 0 → 0 l, 200 → 9 l and 500 → 28 l, the app writes two segments. The first starts at 0 with a = 0.045 and b = 0, so a reading of 100 gives 4.5 l. The second starts at 200 with a = 0.0633 and b = -3.67. You can also type or correct the segments yourself in Coefficients.
¶ Between, below and above the points
For each reading, the app uses the segment that starts at the highest X that is not above the reading:
| Reading | What the app does | Example with the table above |
|---|---|---|
| Between two points | Applies the segment that starts at the lower point. The result lies on the straight line between the two points. | 350 → 18.5 l |
| Exactly on a point | Gives that point's value. | 200 → 9 l |
| Below the first point | Gives 0, whatever the first point's value. | -5 → 0 l |
| Above the last point | Continues the last segment's line. The app does not stop at the last point's value. | 600 → 34.3 l |
So measure a point at the lowest reading the sensor can send and another at the highest. Without them, low readings fall to 0 and high readings keep growing past the real maximum.
¶ Lower and upper bounds
Lower Bound and Upper Bound set the range of acceptable values. Both are optional.
- The app discards a reading outside the range. The field has no value for that message, and the unit card and reports skip it. The app does not replace it with the nearest bound, although the hint in the dialog says so.
- The bounds include their own values: with Upper Bound 300, the app keeps a value of 300 and discards 300.1.
- Apply after calculation decides what the bounds test. Off, which is the default, they test the value before the table converts it: the reading, or the result of the field's expression. On, they test the converted value.
- Bounds also apply to a field that has no segments. The app keeps the value when it is in range and discards it otherwise.
¶ Where calibration sits in the calculation
On every message, the app computes each sensor field in this order:
- It reads the parameters and other sensors the field's expression names.
- It works out the expression, including any condition.
- With Apply after calculation off, it checks the result against the bounds and discards a value outside them.
- It converts the result with the calibration table.
- With Apply after calculation on, it checks the converted value against the bounds instead.
Another sensor that reads this field, such as [Fuel tank#level], gets the value after all these steps.
¶ Tables, expressions and conditions together
The table converts whatever the expression returns. Keep the expression to the bare parameter, {fuel_lvl}, when you calibrate a probe: the points you measured are readings of that parameter.
A condition changes which value the field returns, so it would make a table measured earlier wrong. For that reason, once a field has a table, the Conditional tab locks conditions until you clear the table. You can add a table to a field that already has a condition. See Sensor conditions.
¶ Next steps
- Create a calibration table
- Calibration table dialog: every control, the CSV format and the messages.
- Set up a fuel level sensor