Automatically translate this page?
18 July, 2019

flespi message parameters: finding the common language

What a flespi message can carry and how to make use of it.

If you are doing anything with flespi, you are most likely dealing with flespi messages. A message in flespi is the entity aggregating a set of parameters from a single tracking device received at the same time. 

What is special here?

Is flespi message the same as the device message? Not exactly. When a new message comes from a tracking device into the flespi channel, it gets parsed according to the protocol specification and saved in the unified JSON format with a few valuable additions.

Each flespi message is appended with an ident parameter that stores the unique identifier of the tracking device (IMEI, serial number, etc. depending on the device type). A message without ident is considered invalid in flespi and cannot be operated. Symbols '#', '+', '/', and all non-printable ASCII characters are not allowed in idents.

Flespi also adds a bunch of other parameters:

  • timestamp — the time in UNIX time format when the telemetry was collected (reported by the device usually according to its internal clock)

  • server.timestamp — the time when the message was received by flespi channel (in UNIX time format)

  • channel.id — the ID of a channel handling the connection

  • protocol.id — the ID of a protocol the channel is configured to work with

If you have the flespi device registered for the tracker with the given ident, the following parameters will be added to the flespi message as it gets copied into the device-specific storage:

  • device.id — ID of the device that received the message

  • device.name — the name of the device that received the message

  • device.type.id — ID of the device type for the device that received the message

Therefore, if you want to send a message to flespi (say to an HTTP or MQTT channel), make sure to add at least the ident parameter. 

Obviously, messages coming from the tracking devices contain a lot of parameters about geolocation, CAN data, fuel, alarms, and more. And all of them, as stated above, convert into a unified naming scheme. The convenience of this naming scheme is that it is recognized across the flespi ecosystem. E.g. if the device coordinates have position.latitude and position.longitude parameters, it’s possible to visualize the point on the map in TrackIt.

Can I see all of them?

You can see the exhaustive list of parameters natively supported by the flespi platform using a dedicated REST API request. Select the information you want to get for each parameter (at least the name or select nothing to show all info) and click Try it out!

flespi message parameters list

The list of parameters supported in the specific protocol can be found on the Parameters tab of the given protocol’s page:

list of protocol parameters at flespi.com

or in the protocols REST API

request protocol parameters in rest api

This is the result of clicking Try it out! button: 

get protocols parameters in rest api

Can a message contain custom parameters?

Absolutely. For generic protocols, such as HTTP and MQTT, you can send any additional parameters and they will be saved in the message as is.

For such protocols as Wialon IPS, Wialon Retranslator, and WiaTag any custom parameters you send will be prefixed by the "custom" tag, e.g. "custom.unspecified-name".

How do I get specific messages?

Flespi is a flexible platform — it offers several possibilities to extract the data: HTTP REST API, MQTT, and streams. Pick the one that fits the architecture of your project best.

***

Flespi messages have some specific attributes and features you’d better be aware of. Now that you’ve read this article, you should feel more comfortable dealing with messages in flespi and getting the most out of them.



Get the latest updates and monthly newsletters from flespi in your inbox

22 August, 2019 | flespi features | Evgenij Spitsyn

MapView: draw maps faster & embed easier

Plug the map into your web app and render the necessary elements.

14 August, 2019 | flespi features | Evgenij Spitsyn

FormBox: generate forms based on a JSON schema

How to automate the process of forms creation for your web-project.