Plugins are used to inject user-defined properties and fields into the flespi devices for a variety of special cases such as streaming into government-regulated systems, toll roads services, various telematics data aggregators, and the like.
The device plugins can be used to:
Store custom information in devices and use it in REST selectors. For example, add your customer id or phone number field to all devices.
Publish custom information into device telemetry.
Add custom information into JSON message representation that is published into MQTT and streams. Thus your system will be able to receive some special device attributes or operate based on this data. We are using this for implementing a tollbg plugin and stream. Another use case for this is to stream multiple devices under the same identifier.
Add custom information into JSON message representation that is stored in the flespi database. This allows you to post-process your own data with flespi analytics — build reports and trigger notifications.
Validate data received from device and retain validated parameters value. If message didn't passed validation expression plugin won't be applied to the message at all.
Plugins for devices define the schema of fields, how to validate field values, and what to do with them at different stages of the flespi message pipeline process.
To start using a plugin you need to create one in the Telematics Hub -> Plugins section:
Example 1: static value
We define a “my plugin” plugin for devices with customer_id field that is a positive integer, a required field, and will be published to MQTT and streams:
After creating the plugin we can use plugins REST API or flespi.io GUI to attach devices to the plugin with the specified fields:
Example 2: calculated expression
The example above enabled us to add manually typed values for a given parameter. However, plugins can also add the result of an expression containing other message parameters as the value for the parameter being appended. Here we simply calculate the speed in mph based on the speed in kph taken from the position.speed parameter:
Note that we also specify where this new parameter should appear — in the original message, in MQTT, and in telemetry.
Here's the message content:
Here's the telemetry:
And here's the value from the respective MQTT topic:
The good thing here is that flespi validates field data according to the provided schema — you cannot specify invalid data for the fields or change plugin specification in such a way that can corrupt the device data integrity.
The current configuration of devices attached to the plugin can be retrieved via the REST API or by subscribing to flespi/state/gw/plugins/+/devices/+ MQTT topic.
Read a comprehensive article on plugins here.