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 variables in the scripts which are mapped 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 (eg. if the device has never sent it). You should always handle this “missing variable” case to avoid evaluation errors.
  • The returned result should be convertible 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;

  • 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 synchronised 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 tracking points or using SimOne.