- Essentials
- How to find all message parameters supported for a specific protocol?
- Message parameter naming
- How to access messages?
- How to change message storage period?
- How to fix missing message parameter values?
Essentials
A message is a number of telemetry parameters received by the flespi channel from a single tracking device grouped by the time the data had been collected by the device. 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;
peer — the IP:port used by the device to open connection to a channel;
protocol.id — the ID of a protocol channel is configured to work with.
If a 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 the channel operated over the specified protocol can be found on the appropriate protocol page, e.g. https://flespi.com/protocols/teltonika#parameters.
Here's how a resulting JSON message usually looks like (the number of fields varies depending on the protocol):
{
battery.voltage : 3.938
channel.id : 429
device.id : 182083
device.name : "Vehicle"
device.type.id : 744
engine.ignition.status : false
event.priority.enum : 0
external.powersource.voltage : 12.64
gnss.state.enum : 1
gnss.status : true
gsm.cellid : 11511
gsm.lac : 108
gsm.mcc : 257
gsm.mnc : 1
gsm.operator.code : "25701"
gsm.signal.level : 80
ident : "111115555599999"
movement.status : false
peer : "185.213.2.10:59924"
position.altitude : 244
position.direction : 281
position.hdop : 0.3
position.latitude : 43.955218
position.longitude : 37.661918
position.satellites : 15
position.speed : 0
position.valid : true
protocol.id : 14
server.timestamp : 1678346072.792816
timestamp : 1678346071
vehicle.mileage : 36713.703
}How to find all message parameters for a specific protocol?
You can find the Message Parameters in the flespi panel in the left-side menu:
When the new screen opens, you see the entire list of parameters across all protocols supported in flespi.
The Protocols count value tells how many protocols use the given parameter. Click anywhere on the parameter line to see which protocols are using it.
Use the Protocols drop-down to pick the target protocol you want to see parameters for. Additionally, use the Filter field to narrow down the search by part of the parameter name or description.
You can also find the list of all supported parameters for a specific protocol on the Info tab for the channel working over the given protocol:
P.S. You can always get the same information by performing a proper API request.
Message parameters naming
The naming of message parameters is unified, which 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.
How to access messages?
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.
Below is the scheme showing the path of a message 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:
Stored in the channel buffer to be returned in GET /channel/messages REST API call
Pushed via MQTT to the topic flespi/message/gw/channels/#
Sent via a stream
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 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 a stream
How to change message storage period?
The lifetime of a message is limited by the time-to-live parameter of the message buffer. Setting the messages_ttl parameter in the channel configuration to 0 will result in the deletion of all messages in the channel buffer.
Learm more about how to adjust message TTL and rotation size to optimize storage on the platform.
How to fix missing parameter values?
If you need to make the parameters in your messages more consistent, you can use a special flespi plugin that will fill in the specified parameters with the values from telemetry (with the last known values of these parameters).