Device Mapper Scripting
For device mappers we have introduced a concept called scripting. GpsGate variables can now be assigned the result of a user defined script, this allows you to create more complex mappings between variables.
In this article I will show you examples of how to use scripting in a device mapper.
These are the most common problems that are easy to solve with scripting:
- Inverting a boolean variable.
- Using more than one input variable to produce one output variable.
- Extracting bits from an accumulated variable.
- Assigning text values to set of value ranges when each range indicates a specific status.
Scripts are managed in step 4. Script in the Device Mapper window as shown below. (_EditDeviceMapperScript privilege is required to access the 4. Script step).
In this example in the left column we have two script mappings (CustomString, CustomAnalog1) which use scripting. In the right column the details (Output, Script) of selected mapping are shown. When the script is executed the result is assigned to the output variable. Using the Edit button you can open the script editor window to modify the script. The Remove Script button will remove the currently selected mapping. You can add a new one by clicking on the Add button.
Good to know
- 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.
Add new script
In this example I will show you how to create a new script. Lets consider the following scenario: the device provides an accumulated analog value containing acceleration data in the bits 2-9.
1) Go to Admin → Device mappers, and select the mapper you want to edit.
2) Make sure that all the variables you want to use in your script are mapped in the “3. Mapping” step, you can only work with the mapped variables in the scripts. In this example the accumulated data comes from the Analog1 device input. That input is mapped to the CustomAnalog1 output as shown below:
3) Go to step “4.Scripts”, and click the Add button. From the drop-down list, select a suitable output for the script result. In this example “Acceleration” is used as the output variable of the script.
4) Click the Edit button to open the script editor window.
5) In the main area of the window an auto-generated template with mapped variables is shown.
We want to extract the bits 2-9 of the CustomAnalog1 accumulated variable. Here is a sample value in binary form: “0110001110010101” and we want to extract the highlighted bits.
To solve this task I have replaced the template with the following script:
6) You can run the script by clicking the Test Script button. The output variables will be assigned using the Test Values (left 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 can not save a device mapper if you have any errors in the scripts.
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 the script with a device. GpsGate provides a simulator for the “GpsGate TrackerOne” device that can be very helpful during the script development. For more information about SimOne click here
You can use the Terminal to view how the data is exchanged between server and tracker. It also shows the output value of script mappings for each incoming message.
For more information about the Terminal plugin click here
You can use the _ReadMessageFields privilege to control the visibility of message variables in the Status and Track Point panels.
All mapped variables are enabled by default. You can disable mapped variables explicitly on Role or Application level.