Combine custom variables and device mapper scripting

In this guide, we want to demonstrate a real-life use of custom variables and device mapper scripting. Device mapper scripting can solve problems of the sort "I have one or more input signals from my GPS tracker and I want to decide what to do in the output using different formulas." Custom Fields allow us to assign non-standard properties to our assets like registration number, fuel tank size, asset colour, etc.

A practical case using both solutions would be, for example, if we have different fuel tanks in different assets (assets of the same type can have different fuel tank sizes). You can adapt the fuel level signals to display the correct values (litres for example) for your fleet. The difference between non-linear mapping is that in this case we will use a asset property and a GPS input to generate the correct output.

Steps

1. Enable the required properties for your applications
2. Input the custom variables
3. Set the custom variable to your asset's value
4. Input your script in your device-mapper
5. Test the script
6. Result

Enable the required properties for your applications

Read how to access the privileges and features of an application and enable the following two roles:

_EditDeviceMapperScript
_EditCustomField

Input the Custom Variables

1. To add a Custom Variable, we need to go to the Assets panel menu > Manage Custom Fields

2. Add a new variable of the type Text called Fuel_Tanks. You can add a default value or you can insert for each asset the value. (Edit asset option from the Assets panel list)

3. Refresh the browser for the changes to apply

Set the custom variable to your assets

1. To add a new property to our assets, we need to modify the asset in the Type Editor by adding a custom field. Navigate to the Assets menu and select Type Editor.

The new property is located under Device type > Details of the user properties.

2. Check both checkboxes to set this parameter as mandatory for future new assets.

3. Define the value for each asset by editing the asset.

Input your script in your device mapper

1. Go to Main Menu > Admin > Device Mapper and select the correct tracker for your assets. The input signal we want to modify with our script needs to be mapped here.

In the example, the input signal will be the Analog01, which gives the number of volts (reflecting the tank capacity for the given asset).

2. Read the Device Mapper Script Guide  to enable the device-mapper script

3. Under the Script device mapper, select the Output variable: Fuel level.

3. Press on Open Script Editor 

Some useful tips for your Javascript code: 

• To get a variable from the Device Mapper use fields.get(‘device_mapper_variableName’, default_value)
• To get a variable from the Custom Fields use user.getCustomFieldValue(‘custom_field_label’)
• To log entries to allow you to debug your code, use log(‘variable_name’)

The following script is JavaScript and is just an example of the transformation you can do to your input. You need to have some knowledge of JavaScript or programming to create your script.

var Fuel_level_percent = fields.get('Analog01', 0);
var Tank_type = user.getCustomFieldValue('Fuel_Tanks');
var fuel_level = Fuel_level_percent * Tank_type /100;
return fuel_level;

You have some tools in the script editor to test your scripts. You can modify the Device Mapper variable values and use the logs in the code to verify if the result is correct

Result

You can finally see the changes in your tracking points for a given asset when the signal fuel level is received. And with the device mapper scripting, you can have these values converted, for example, to liters (using the tank type defined in the asset properties).

You can always make your tests within the Script Editor or if you want to submit signals to the platform to see the response you can also use the asset simulator.