Basic: A message is a number of telemetry parameters received by the flespi channel from a single tracking device grouped by the time of receipt. Each message must have:
ident — a device identification field
Note: Symbols '#', '+', '/', and all non-printable ASCII characters are not allowed in idents.
timestamp — time when telemetry was collected (in UNIX time format);
server.timestamp — 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 channel is configured to work with.
If message is coming from the device, registered in flespi, additional messages fields are expected:
- device.id - the ID of the corresponding device;
- device.name - the name of the corresponding device.
- device.type.id - the ID of the corresponding device type;
All other message parameters depend on the device protocol, type, configuration and plugins, attached to the device. The full list of possible parameters accepted by channel operated over specified protocol can be found on the appropriate protocol page, e.g. https://flespi.com/protocols/teltonika#parameters.
Read more about flespi message parameters in a dedicated blog post.
The naming of message parameters is unified, it means that parameters with the same meaning received from different trackers over different protocols will get identical names and measurement units in flespi. The full list of parameters supported by flespi can be retrieved via an appropriate API call. A message is represented by the plain JSON object with parameter names as keys.
There are three ways to access messages received by the flespi channel:
HTTP REST API call — get messages from the channel’s internal buffer.
Push-mode streams — flespi will push messages to the specified platform.
MQTT API — receive messages via MQTT client subscribed to the appropriate topic.
Advanced: The following image illustrates the full message path from the tracking device through flespi and to the flespi user:
A device sends a message to the flespi channel. As soon as the flespi channel accepts the message, it can be delivered to the user on channel level in one of the following ways:
If there is a registered device with a matching ident field, the message goes to the device instance and can be delivered to the user on the device level in one of the following ways:
Stored in the device’s message buffer to be returned in GET /devices/messages REST API call
Pushed via MQTT to topic flespi/message/gw/devices/#
Updated in the telemetry structure so the user can receive only changed message parameters
Sent via stream
To understand the message lifecycle in more detail please refer to this article.
The lifetime of a message is limited by the time-to-live parameter of the message buffer.