MQTT topics guide

The structured collection of main flespi MQTT topics grouped by the entity.

Should you decide to consume updates from the flespi platform in a push-based MQTT way, you need to know the available MQTT topics to subscribe properly to the desired data source. 

Important! You can not publish MQTT messages to any topic that starts from "flespi/". All topics in this article are reserved for exclusive publication by the flespi platform only usually as an indication of some event. Any MQTT message published by user to such a topic will be discarded by the Broker.

Navigate to the list of MQTT topics for the required entity:

How to explore the topics?

We suggest using our MQTT Board tool as a friendly playground for all your MQTT experiments. 

mqtt board add topic to explore

Just create a Subscriber, paste any of the below topics, and click the Play (Subscribe) button. 

mqtt board topic payload

Devices

Since flespi is a device-centric platform, devices have the most topics associated with them.

Topic

Description

flespi/state/gw/devices/{id}/+

Device main fields

Access the device’s connected, last_active, and other useful characteristics. 

flespi/state/gw/devices/{id}/telemetry/+

Device telemetry values.

Use this topic to separately get the latest value of each message parameter registered in the device.

flespi/message/gw/devices/{id}

New message received by the device

Use this topic to get new messages from the device in real-time.

flespi/interval/gw/calcs/+/devices/{id}/created,updated,deleted


Intervals generated by calculator assigned to the device were created, deleted or updated

Monitor intervals generated for this device and their status changes. Recommended for advanced usage of analytics events.

flespi/interval/gw/calcs/+/devices/{id}/activated,deactivated

Calculator assigned to the device triggered change to active or inactive state according to calculator configuration

Monitor current state change of the devices assigned to calculator. Recommended to use for notifications system on top of calculators.

flespi/state/gw/devices/{id}/settings/#

List of device settings

All device settings with all their current fields (the same as you can see on the Settings tab for the device).

flespi/state/gw/devices/{id}/settings/+

Settings: current value

Get the list of settings with their current values.

flespi/state/gw/devices/{id}/settings/+/pending

Settings: pending value

Get the list of settings that have the new value sent to them but not yet applied.

flespi/state/gw/devices/{id}/settings/+/status

Settings: status

Find out if the setting was read, applied, or unreadable. Find the table of possible setting statuses in devices API docs.

flespi/state/gw/devices/{id}/connections/+

List of active TCP connections from device

Device can establish only single primary connection and multiple secondary connections, for example during video streaming or uploading, sending its data via FTP, etc

flespi/log/gw/devices/{id}/settings/+/updated,set,accepted,rejected,canceled,cleared,unreadble,sent

Settings: logs

Get real-time logs indicating the statuses the device setting goes through. The status can be one of the following:


updated - device delivers new setting value by itself or upon request


set - flespi received a REST request to set a new setting value and accepted it for sending to the device


accepted - flespi sent a command to update the setting and the device responded “accepted successfully” (if the protocol supports such acknowledgment)


rejected - flespi sent a command to update the setting and the device responded with an error (if the protocol supports negative acknowledgment) or the device didn’t respond to 10 attempts to send a command


canceled - flespi received a REST request to delete a new setting value BEFORE the device confirmed its acceptance (or before the device responded with an error or before 10 attempts to send a command)


cleared - flespi received a REST request to delete the current setting value (that device accepted or previously sent to flespi)


unreadable - flespi sent a command to read a device setting 10 times and every time the device responded with an error or ignored the command; flespi will not attempt to read this setting until the user clears it via REST API


sent - once flespi sent the new setting value to the connected device

flespi/log/gw/devices/{id}/commands-queue/+/processed,queued,sent,canceled,expired

Commands queue: logs

Get real-time logs indicating the statuses the device command goes through in the commands queue. The status can be one of the following:

processed - flespi received request to place a new command in the commands queue


queued - command has been placedin the commands queue


sent - once flespi sent the new command to the connected device


canceled - flespi received a REST request to delete a new setting value BEFORE the device confirmed its acceptance (or before the device responded with an error or before 10 attempts to send a command)


expired - the command was deleted from the commands queue because the command TTL elapsed

flespi/log/gw/devices/{id}/mediastream/started,stopped

Live video streaming from device started or stopped

flespi/state/gw/plugins/+/devices/{id}/#

Plugins assigned to device

Get the list of plugins assigned to this device and their status.

flespi/log/gw/devices/{id}/#

Device logs

Detailed records about all events related to the given device.

Devices API docs:  https://flespi.io/docs/#/gw/devices

Channels

If you rely on channels to consume a flow of data from the telematics devices, these are the topics you may use:

Topic

Description

flespi/state/gw/channels/{id}/+

Channel main fields

Access the channel’s enabled, connections_count, messages_size, blocked status, and other useful characteristics.

flespi/state/gw/streams/{id}/channels/+/#

Streams assigned to channel

Get the list of all streams the channel is forwarding data through.

flespi/message/gw/channels/{id}/+

New messages from device(s) received by channel

Use this topic to get new messages arriving to the given channel in real-time (from devices operating via this channel’s protocol).

flespi/log/gw/channels/{id}/#

Channel logs

Detailed records about all events related to the given channel.

Channels API docs: https://flespi.io/docs/#/gw/channels

Streams

If you use a stream to forward data from the flespi platform to a specific destination platform, you may find some of the topics below useful.

Topic

Description

flespi/state/gw/streams/{id}/+

Stream main fields

Access the stream’s enabled, connected, URI, queue_size, and other useful characteristics.

flespi/state/gw/streams/{id}/devices/+/#

Devices assigned to the stream

Get the list of all devices the stream is forwarding data from.

flespi/state/gw/streams/{id}/channels/+/#

Channels assigned to the stream

Get the list of all channels the stream is forwarding data from.

flespi/log/gw/streams/{id}/#

Stream logs

You can use this topic to monitor the operability of your stream. Find the event codes and error codes to catch in the streams API docs.

Streams API docs: https://flespi.io/docs/#/gw/streams

Calculators

As a key entity of the flespi analytics engine, calculators feature a few MQTT topics to subscribe to the frequently required data.

Topic

Description

flespi/state/gw/calcs/{id}/+

Calculator main fields

Access the calculator’s counters, selectors, intervals_rotate, intervals_ttl, and other useful characteristics.

flespi/state/gw/calcs/{id}/devices/+/synced

Calculator state (synced or not)

Get the current calculator sync state for each of the assigned devices (or for some of them).

flespi/state/gw/calcs/{id}/devices/+/last

Last detected interval

Get the freshest interval generated by the calculator for each of the assigned devices (or for some of them).

flespi/state/gw/calcs/{id}/devices/+/active

Active interval

Use to monitor the current state of the interval (active or not).

flespi/interval/gw/calcs/{id}/devices/+/created,updated,deleted

Interval created, updated, and deleted events

Use to catch intervals status changes: created, updated, deleted. Recommended for advanced usage of analytics events. 

flespi/interval/gw/calcs/{id}/devices/+/activated,deactivated

Calculator assigned to the device triggered a change to active or inactive state according to calculator configuration

Use to track active intervals when they appear (get triggered) and disappear (become no more actual).

Calculators API docs: https://flespi.io/docs/#/gw/calculators

Complete list of flespi MQTT topics

Above we expanded only the most widely used MQTT topics. The exhaustive list of ALL MQTT topics for ALL flespi entities is available in the flespi panel: https://flespi.io/#/topicsdirectory

flespi mqtt topics directory

Flespi MQTT extras

In addition to + or # topic multipliers in the subscription (e.g. subscribe to flespi/# to receive all messages from all flespi topics) you can use so-called topic selectors - use comma-separated list of words in each topic part. For example instead of subscribing to 4 topics for device ID 100 and 200 for analytics events activation and deactivation it is possible to subscribe to a single topic flespi/interval/gw/calcs/+/devices/100,200/intervals/activated,deactivated which will provide equivalent results.

For even more customization you may apply powerful filtering for incoming messages on the MQTT broker side.

Even though the flespi MQTT broker is completely MQTT5-compliant, it also features some extra functionality that makes working with the flespi topics structure more convenient.


See also
UI options to control the order of items received via REST API
MQTT bridge is a very useful tool when you need to separate and partially isolate parts of your system, as well as not be fully dependent on a third-party MQTT broker.