Automatically translate this page?

Plugins — customize messages for flespi devices

Complement and/or transform your device data to meet the requirements of a third-party platform.

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 the message doesn't pass validation expression, the 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:

flespi panel telematics hub plugins

Example 1: static value

We define a “my plugin” plugin for devices with a customer_id field that is a positive integer, a required field, and will be added to MQTT, streams, and telemetry:

flespi new plugin configuration

After creating the plugin we can use plugins REST API or flespi.io GUI to attach devices to the plugin with the specified fields:

flespi attach plugin to device

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:

flespi plugin expression result

The store option (enabled by default) instructs to add the new parameter in the original message, in MQTT, and in telemetry.

Here's the message content:

plugin data in message content

Here's the telemetry:

plugin data in telemetry

And here's the value from the respective MQTT topic:

plugin data in 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.


See also
Using flespi plugins to pack together the data coming from two or more related devices.
The location for all data in your flespi account.