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

  • Go to SiteAdmin > Click in the application name > Privileges and Features > Admin > _EditDeviceMapperScript

How to access the Device Mapper Script

1. Login to your application

2. Select the menu Admin > Device Mappers > 4. Scripts

3. Cick in + Add to select an output

4. Select your output then click on Edit 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;

mceclip0.png

Replace a value for 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.

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.