The "msg-expression" plugin type is used to add a new message parameter with the value calculated in the specified expression. If the logic that you need to apply to the message parameters transformation is not that straightforward take a look into more powerful msg-pvm-code plugin.
How to use
Click on the "+" button in the Telematics Hub -> Plugins section to create a new plugin:
Let's define a new plugin that will calculate the current speed in mph and add it to the speed.mph message parameter:
Then we need to assign this plugin to the right devices. Go to the Plugins tab for the required device and click the "+" button:
And then you should be able to see the new calculated field in the new device messages. Go to the Logs & Messages tab for the given device to check:
Done.
Advanced note: replacing existing parameters
If you specify the name of the existing message parameter (e.g. position.altitude) as the plugin field name, the respective original message parameter will be replaced by the value from the plugin:
Case: how to detect value change
A frequent need is to detect whether a specific parameter has changed compared to its previous value. To achieve that, you can create an msg-expression plugin that checks if a particular parameter (or set of parameters) has changed "param1 != previous('param1')" and then adds the parameter "changed = true". After that, you can use a validate message expression "changed == true" in the item configuration.
Case: how to detect over-speeding per device
Another popular use case is to use device metadata to store there a maximum allowed speed for this device. With msg-expression plugin it is possible to access such value and add to the message either the maximum speed limit itself or over-speeding condition. For example your maximum speed limit is stored in the metadata under field "max_speed". In that case the expression "position.speed > metadata('max_speed')" will detect over-speeding condition.
To filter out plugin application for devices that do not have such field in their metadata specify "not(isnull(metadata('max_speed')))" in plugin's validate_message configuration. You may event set even more complex expression inside validate_message, like 'position.speed > metadata("max_speed") && not(isnull(metadata("max_speed")))' to apply the plugin only when speed limit is set and it is violated.
Change log
Subscribe to the expressions plugin change log to stay in sync with any updates.
More plugin types
Find a comprehensive list of available plugin types here.