- Essentials
- How to find all message parameters supported for a specific protocol?
- Message parameter naming
- Position parameters
- How to access messages?
- Message storage and ordering
- 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 with microseconds in fraction part);
server.timestamp — time when the message was received by flespi channel (in UNIX time format with microseconds in fraction part);
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
}You can add, delete or update parameters in the device messages with plugins. However keep in mind that system-level parameters such as ident, device.id, channel.id, server.timestamp, etc are immutable and can not be modified - only timestamp parameter is allowed to be corrected.
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
Message parameter names in flespi must consist strictly of lowercase letters (a-z), uppercase letters (A-Z), digits (0-9), periods (.), and underscores (_). All other characters in parameter name are prohibited.
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.
We have a special policy for message parameter changing within each protocol and device type. We notify you about parameter name changes at least 7 days in advance (usually 2 weeks). This notification period can be increased to up to a 2 monthes when the change affects a significant number of devices. During the transition period we register device telemetry both with an old and new parameter names.
Integration of new parameters to protocols, including the normalization of custom.* parameters, is performed without preliminary notice. If you need meaningful data within a custom.* message parameter in your production-grade system, please contact us via the HelpBox chat and schedule the integration of these parameters into the protocol. Only parameters with a normal naming scheme are subject to preliminary notification before any change.
To stay current with any changes in the protocol and prevent any outages in your integration, we strongly suggest subscribing to the appropriate protocol change log topic on our forum to receive updates via email.
Position parameters
Parameters that starts from position in their name e.g. position.latitude or position.longitude are special parameters related to the position information. They are processed by flespi in a special way:
- In device telemetry all positional parameters that present in last message automatically generate virtual telemetry property with name telemetry that is JSON object which keys are position related parameters without position in their name e.g.: position={"latitude": 10, "longitude": 20, "speed": 0, "valid": true}.
- If position.latitude or position.longitude values are incorrect (non-numerical, zero or out of allowed WGS-84 values) they are automatically removed from the message which is amended with additional parameters to indicate this update: "position.valid": false and "position.skipped": true.
- If the source of position information is not GNSS extra parameter position.source: "<source>" is added, where <source> can be wifi, lbs, ble or other system that provided device with coordinates. Such operations are usually performed by corresponding plugin.
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
Message storage and ordering
Messages are independently stored in channels and devices. In channel storage all messages are ordered by their reception time which is indicated in server.timestamp parameter. While in device storage messages are stored ordered by RTC time reported by the device which is indicated in timestamp parameter.
Device storage merges all messages with the same timestamp into one message by overriding same parameters with new values and appending new ones. If under the same timestamp more then one distinct message can be reported by the device flespi stores such messages under timestamp.key parameter which in its fraction part usually contains event or packet seqno.
Thus when message being registered uses same timestamp as already stored message you will see multiple messages with the same timestamp in channel messages storage and only single merged messages in device messages storage.
Also channel messages are always messages that parsed by the channel protocol originally written by flespi engineers with standard parameter names defined for given protocol while device messages can be modified by plugins without limitations.
The lifetime of a message is limited by the time-to-live parameter of the corresponding 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 and channel will no longer store messages.
Same applies to device message storage. However device messages storage can additionally set rotation size to automatically delete older messages once the buffer reach certain size. Learn more about how to adjust device message TTL and rotation size to optimize storage on the platform.
It is not possible to delete device messages. You can only update their parameter values using POST /gw/devices/X/messages API call. If you will specify exact timestamp (and optionally timestamp.key) parameter values from original message you will be able to rewrite other parameter values in that message. For example you can set position.valid to false for messages with corrupted GPS data. If you can detect corrupted or invalid parameter values during the message registration phase you can apply msg-cancel plugin to prevent registration of such messages to the device at all.
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).