Plugins — customize messages for flespi devices

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

Essentials

  • Plugins are the key instance in flespi responsible for the transformation of the received message before it departs to the destination.

  • Plugins apply to device messages.

  • You can apply multiple plugins to a message in the specified order.

The device plugins can be used to:

  • Attach custom static information to devices and use it in REST selectors. For example, add your customer id or phone number field to devices. Note: this custom info will not be added to the device JSON messages.

  • Add and store custom information as a part of the device JSON message. As a result, this custom data will be available in device telemetry, via MQTT, in streams, and for analytics.

  • Validate data received from the device and retain validated parameters value. If the message doesn't pass the validation expression, the plugin won't be applied to the message at all.

  • Inject values obtained from third-party services, e.g. geocoding or LBS data

  • Delete specified parameters from the received messages.

  • Change message parameters based on the user-defined custom logic written using our special PVM language or by utilizing your infrastructure via webhook.

How plugins work

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. 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.

Types of plugins

Below is the list of currently supported plugin types:

Plugin type

Description

item-fields

add static fields to the designated item, some of the fields can be stored as message parameters

item-telemetry

add cached telemetry values in place of missing device message parameters

msg-expression

add new message parameters as a result of evaluating expressions

msg-erase

remove the listed parameters from the message

msg-merge

restore message parameters from existing message with the same timestamp

msg-geofence

detect if the position from a given device message is inside a specified list of geofences; add parameters with the status (in/out) and geofence name to the device message

msg-pvm-code

execute PVM code to process the message

msg-copy

merge messages from multiple devices into one device or create copies of devices

msg-cancel

cancel/prevent registration of message into device

msg-webhook

send messages to a script on a your server for custom processing

ble-indoor-position

add BLE tag coordinates to device messages (for indoor monitoring)

msg-dtc-decoder

decode DTC code to human-readable description

msg-param-calibrate

convert value with a stepwise linear function

google-reverse-geocoding

resolve the position address using Google reverse geocoding and add it to the message

nominatim-reverse-geocoding

resolve the position address using Nominatim reverse geocoding (OSM) and add it to the message. Public and private servers supported.

here-reverse-geocoding

resolve the position address using Here reverse geocoding and add it to the message

wialon-reverse-geocoding

resolve position address using reverse Gurtam Wialon geocoding and add it to the message

locationiq-reverse-geocoding

resolve the position address using LocationIQ reverse geocoding and add it to the message

gisgraphy-reverse-geocoding

resolve the position address using Gisgraphy reverse geocoding and add it to the message

wialon-lbs-geocoding

resolve position coordinates using LBS Wialon geocoding and add them to the message

google-wifi-geolocation

resolve Wi-Fi router MAC address information into location data using Google Wi-Fi Geolocation API and add them to the message

unwiredlabs-geolocation

resolve Wi-Fi router MAC address information and cellular network data into location data using Unwiredlabs geolocation API and add them to the message

wialon-overspeeding

detect speed limits using Wialon API and add them to the message

We can develop new plugins upon request. This will require ordering a specific number of custom engineering hours depending on the complexity of the plugin .

How to create a plugin?

  1. Log in to the flespi panel
  2. Navigate to Telematics hub -> Plugins and click the "+" button in the bottom right corner to add a new plugin:
    create a plugin
  3. Give the new plugin a name, pick the proper plugin type depending on the task, configure it, and click Save:
    configure a plugin
  4. Go to the Devices tab for the plugin and assign the devices that need to be affected:
    assign devices to plugin

Advanced plugin configuration

Plugins priority

If you assign several plugins to a device, you may want to apply them in a specific order. Use the priority parameter in the plugin configuration to arrange the required order. The higher the number in the priority field, the earlier the plugin will apply.

Data validation

Use the validate_message field in the plugin configuration to specify the validation expression that should succeed for the plugin to apply. If no validation expression is specified, the plugin will apply to all messages.

flespi plugin configuration validate message

Timezone

Use the timezone field in the plugin configuration to specify the correct timezone for all time/date-related operations in selectors and counters.

flespi plugin configuration timezone

***

Read a comprehensive article on plugins here.

Plugins API

To perform any operations with the plugins, use the plugins API.

Troubleshooting

You can visually check which plugins affected the device message during the registration by opening device in flespi panel UI (or in Toolbox), selecting "Logs & Messages" tab and clicking on the message. This will popup the message information box in the right side of the screen where you can trace the whole chain of events associated with this message: when it was recorded by the device, when it was delivered to flespi channel, when and what plugins processed it and so on:

In case of any issues with particular plugin check its Logs tab. For detailed troubleshooting the raw traffic generated by the plugin is available under Traffic button. 

For plugins that communicate with external services (the majority of plugins) you can quickly navigate to a raw traffic associated with certain plugin event from its Logs tab by right clicking on a log message and selecting "Show traffic" in the context menu. This action will switch the view to a traffic view and navigate to the corresponding traffic generated by the plugin and related to this event in plugin logs.

What's next?

  • To forward the parsed data from your devices, explore our streaming options.
  • To apply real-time analytics to device messages, use calculators.

Before you will start using flespi on a full scale we suggest to watch detailed videos from our conference. Invest your time into watching them now to save much more time and money later, when you will implement your project:


See also
Using a plugin to convert value with a stepwise linear function
Explore the pros and cons of various reverse geocoding services supported by flespi.