Introduction

With the custom measurements feature you can create specific measurements for your sensors.

Catalog sensors measurements

When you associate a sensor to a thing , Pilot Things automatically decodes the sensor messages to create measurements.

In the example hereunder, the sensor returns Humidity and Temperature in Celsius.

To illustrate the custom measurements we will add HeatIndex measurement to this sensor and change the temperature unit to Kelvin.

Custom Models

The model usually represents the real usage of your sensor. You could consider it as a digital image of the real world.

For example if you use temperature sensors to get the outside temperature you would create an OutsideTemperature model. If you use a level sensor to monitor bins fullness in a waste management scenario you would create a model for each bin type : large bin and small bin for instance.

The model includes measurements coming from the sensor and custom measurements that you create. 

To create new measurements you must create a new custom model first. Go to Custom Model menu.

Then on the right panel click on New Model:

Fill your model name like Outside Temperature and some description if needed.

On the Attribute right panel  click on add to create your first attribute. 

For this example we added 3 new attributes: Humidity, Temperature and HeatIndex as follow:

Decoding function

Now we have created the attributes it is time to define how to calcule them. Click on Edit Script just under the attributes list:

The function editor uses java script language. The function parameters are:

The previous measurements could be used to calcule differences. A typical use case is to calculate consumption based on an index difference.

In that example we use a sensor that gives humidity and temperature values and we would like to calculate the HeatIndex. 

The sensor gives the temperature in Celsius that we convert in Kelvin.

The function is:

CalculatedIndex = -42.3799 + 2.049*measurements.temperature + 10.14*measurements.humidity + -0.22*measurements.temperature*measurements.humidity;

return {
           Temperature: measurements.temperature + 273.15,
           Humidity : measurements.humidity,
           HeatIndex: CalculatedIndex
           };

Copy this function in the editor, It should looks like that:

Then press the save button.

Important notes:

1. Objects don't necessarily send the same measurements inside every messages. So before using a measurement, for exemple measurement.temperature you need to verify if the measurement is available if the following test : if( measurements.temperature !== null )
2. previousCustomMeasurements is also accumulating the measurements. It means if you are processing a message on 01/01/2020, inside previousCustomMeasurements you will find the last value of every custom measurements. Which doesn't mean that the value of the measurement is form 31/12/2019 but from the last time the plateform has received a message which generated the custom measurement you want.

Associate the model

Now that your model is ready you have to associate it to a sensor. Go to the Things menu , select a sensor and press Actions, Custom Model, Associate:

Now that your sensor is associate to the model , go to the sensor detail by clicking on it.

In the measurements panel we could see your new measurements:

You could now display the HeatIndex in a dashboard or use it in an automation rule.

Important notes:

When you associate a custom model with an object it will replace the model from our catalog. So if you don't copy the measurements you want, you won't be able to use them.