18 July, 2019

flespi message parameters: finding the common language [UPD: Apr 8, 2021]

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 the 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 the 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 (e.g. 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 (please note validation for those 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. Or use a convenient tool built into the flespi panel.

flespi panel message parameters tool

You can also find the list of parameters supported in the specific protocol on the Parameters tab of the given protocol’s page:

list of supported message parameters on protocol page

or in the protocols REST API:

request list of message parameters in protocol API

Here's the result of the API call:

message parameters result of api call

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.