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 device 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 vehicles/units like registration number, fuel tank size, vehicle color, etc.

A practical case using both solutions would be, for example, if we have different fuel tanks in different vehicles (vehicles of the same type can have different fuel tank sizes). You can adapt the fuel level signals to display the correct values (liters for example) for your fleet. The difference between non-linear mapping is that in this case we will use a vehicle 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 vehicle'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 Vehicle > Manage Custom Fields

2. Add a new variable of the type List called Fuel_Tanks and add the three different types and their values:

Note: To add more items to the list, just press enter after the last field.

3. Refresh the browser for the changes to apply

Set the custom variable to your vehicles

1. To add the new property to our vehicles, we need to edit the User Type to add the custom field:

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

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

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

Input your script in your device-mapper

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

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

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

3. Select the Output signal (in this case, it's the same as the input because we need to transform the volts to liters depending on the type of tank).

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 codes 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.

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 vehicle 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 vehicle 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 device simulator.