How to convert value with a stepwise linear function?

The msg-param-calibrate plugin converts raw parameter values into engineering values using a custom stepwise linear function: you define the calibration points, the plugin interpolates between them. It is the standard way to turn the raw reading of a fuel level sensor into liters, or a voltage into a temperature.

The calibration is defined per device, and a single plugin instance calibrates up to 3 parameters of a device with their own tables, for example the sensors of several fuel tanks of a truck.

How to use

Click on the "+" button in the Telematics Hub -> Plugins section to create a new plugin:

Select the msg-param-calibrate type and give the plugin a name. The plugin itself has no configuration: the parameter names and the calibration tables are set for each assigned device. The plugin can only be applied to messages that are validated using the expression specified in the Validate message field.

Then assign the plugin to the right devices. Go to the Plugins tab of the device, click the "+" button, select the plugin and add a calibration:

Each calibration has:

• Input parameter name - the message parameter with the raw value, for example lls.value.1;
• Output parameter name - the message parameter to store the converted value into, for example fuel.volume.1. Leave it empty to overwrite the input parameter with the converted value;
• Calibration table - the points of the function, in ascending order of the input value;
• Min error value and Max error value - optional values written to the output parameter when the input value is below the first or above the last point of the table.

For example, the calibration table of a fuel level sensor:

With this table an input value of 587.5 gives 4.9 in the output parameter. Input values equal to a point give the output of that point.

To calibrate more parameters of the same device, for example the sensors of the second and third fuel tanks, add more calibrations to the same assignment, up to 3 in total:

Note: if the input value is out of the table range, the value is not converted and a plugin error is generated in the plugin logs. To handle such cases, specify the Min error value and Max error value that will be set in the output parameter instead.

Note: the calibrations of a device are independent. If one of them fails, the other converted values are still added to the message and the failure is reported in the plugin logs with the name of its input parameter. The message is registered without converted values only when all calibrations failed.

Note: you can change the calibrations at any time after the plugin assignment. To apply the same calibrations to many devices, assign the plugin to a group of devices instead.

Now you can go to the device Logs & Messages tab and see how the values are converted:

Assignment via the REST API

The same setup is available via the plugin assignment API. The assignment fields of a device with two fuel tanks look like this:

{
  "fields": {
    "calibrations": [
      {
        "input": "lls.value.1",
        "output": "fuel.volume.1",
        "table": [{"x": 401, "y": 3.5}, {"x": 530, "y": 4.1}, {"x": 645, "y": 5.7}, {"x": 700, "y": 6.1}, {"x": 803, "y": 7.0}, {"x": 1005, "y": 8.2}],
        "min_y": 0,
        "max_y": 8.2
      },
      {
        "input": "lls.value.2",
        "table": [{"x": 0, "y": 0}, {"x": 1000, "y": 120}]
      }
    ]
  }
}

The second calibration has no output parameter, so the converted value overwrites lls.value.2.

Change log

Subscribe to the msg-param-calibrate change log to stay in sync with any updates.

More plugin types

Find a comprehensive list of available plugin types here.