Device Mapper Scripting

Device mapper scripting lets GpsGate variables be assigned the result of a user-defined script. This allows you to create more complex mappings between variables.

How to enable it

• Navigate to Site Admin → Applications → Manage Applications -> Privileges 
• Enable the following: _EditDeviceMapper

                                               _EditDeviceMapperScript

How to access the Device Mapper Script

1. Login to your application

2. Select the menu Admin > Device Mappers > Choose the device 

3. From the device windows open the Script section and press on +Script button

4. Give a name to the script 

5. Select your output then click on Open script editor to start developing your script

Good to know

• The scripting language is Javascript.
• You can only use mapped variables in step 3. Mapping of the Device Mapper.
• Use fields.get(...) function to get the value of a given variable. The first parameter is the variable name, the second parameter is a default value that can be used if the variable does not exist (e.g. when the device has never sent the value). You should always handle the 'missing variable' case to avoid evaluation errors.
• The returned result must be converted to the type of the output variable.
• When the value returned by the script is null or undefined, the variable is ignored.
• Try to write efficient code and avoid unnecessary instructions in the scripts.
• There is an execution step limit for each script to prevent bad scripts from crashing the server.

Examples

Some examples of problems that are easy to solve with device mapper scripting:

Inverting a boolean variable

The script captures the input HarshTurningDigital and inverts the value.

var booly = fields.get("HarshTurningDigital",false);
booly = !(booly != false);
return booly;

Convert meters to miles

This script converts the input from meters to miles. Useful when you have the metric system in your application but you still want to display a variable in the interface in Miles.

var odoAcc = fields.get('OdometerAcc', 0); // OdometerAcc input in meters
var odoAccMIL = (odoAcc * 0.000621371).toFixed(2); // converts meters to miles and round by 2 decimals
return odoAccMIL;

Replace a value with another

This script captures the value of an input (HarshBreakingDigital) and changes it from false to 0 if the condition matches.

return fields.get("HarshBreakingDigital",false) ? fields.get("HarshBreaking", 0) : 0;

Reset an input based on date/time

This script sets the output to true if current trackpoint date is bigger than specified reset date

var d = new Date(trackPoint.utcTimestamp);
var newTime = d.getTime(); // converts current trackpoint date to miliseconds
var r = new Date('December 08, 2019 00:00:00');
var resetTime = r.getTime(); // converts specified date to miliseconds
log('newTime : ' + newTime);
log('resetTime: ' + resetTime);
log('resetTime-newTime: ' + (resetTime-newTime)/1000/60/60/24); //days until reset time
if(resetTime > newTime)
{
return false;
} else return true;

Change the output of a variable based on the value of an input.

This script captures the Temperature input and gets evaluated according to certain temperature values. Depending on those values, the script changes the output of the CustomString2 variable.

var cargoTemperature = fields.get('Temperature', null);
if(cargoTemperature == null)
{
return 'Unknown';
} else if (cargoTemperature < 10)
{
return 'Normal';
} else {
return 'Hot';
}

Extracting bits from an accumulated variable

The script gets  2-9 bits of CustomAnalog2. Here is a sample value in binary form: 0110001110010101 and we want to extract the highlighted bits.

var CustomAnalog2 = fields.get('CustomAnalog2',0);
var tmp = CustomAnalog2 >>2; // throw 0 and 1 bits away
return tmp % 256; // mod 256 to get the first 8 bits.

Selecting multiple outputs

You can select multiple outputs for a single device mapper script. Cases like a single long string of data needing to be split into many variables should be simpler to handle and have better performance if implemented with one script.

To set: return { 'Var1': 12.3, 'Var2':false, 'Var3':'textabc' }
Setting a single field works the same.
Setting multiple outputs requires enabling the new script engine if not already enabled, in Site Admin > Settings > Scripts.

Tips

• You can run the script by clicking the Test Script button.
• The output variables will be assigned using the test values (right column).
• It is possible to simulate the missing variable case by clicking the checkbox next to a variable. The result and errors are displayed in the console below the script.
• If you close the Edit Script window, the script gets synchronized with the Device Mapper window.
• You cannot save a device mapper if you have any errors in the scripts.

Testing

A log() function is provided to produce debug information about script evaluation. The output of the log function is in the script editor window console in test mode and in the terminal window in production. Here is an example how to use this function in scripts: log(‘sometext: ’ + scriptvariable);

When you are writing a new script, it is useful to test it with a device's tracking points or use the device simulator.