MQTT API
flespi MQTT API is an alternative to the REST API in receiving device messages, all platform logs, connections information etc. The MQTT protocol ensures fast and secure message delivery so one will receive an event message in MQTT session right at the time it appears inside the flespi platform.
You can use flespi MQTT broker separately from telematics by publishing and subscribing any messages to it. MQTT broker is an efficient events bus that can interconnect software (micro-)services between each other.
flespi MQTT broker connection details
- Host — mqtt.flespi.io.
Port — 8883 (SSL) or 1883 (non-SSL); for MQTT over WebSockets: 443 (SSL) or 80 (non-SSL). - Authorization — use a flespi platform token as MQTT session username; no password.
- Client ID — use any unique identifier within your flespi user session.
- Topic — you can publish messages to any topic except flespi/.
- ACL — both flespi/ and MQTT pub/sub restrictions determined by the token.
You may play with MQTT API using MQTT Board - client tool for MQTT debugging and testing. Also you have already preconfigured and connected instance of MQTT Board directly in flespi.io. Just open it inside flespi.io panel - this is the best way to do initial investigation of flespi MQTT API.
MQTT topics
The list of service built-in topics with flespi platform events:
| Topic | Description |
| flespi/message/gw/channels/{channel_id}/{ident} | New message from device identified with {ident} received by channel |
| flespi/message/gw/devices/{device_id} | New message received by device |
| flespi/message/gw/modems/{modem_id}/{phone} | SMS message from {phone} received by modem |
| flespi/log/{api}/{origin}/{event_type} | {event_type} has occurred in {origin}, see platform logs for more information |
| flespi/state/{api}/{origin}/{id} | {origin} object with default properties |
| flespi/state/{api}/{origin}/{id}/{property} | {property} changes in object of type {api}/{origin}, see objects state for more information |
| flespi/state/gw/devices/{id}/telemetry/{parameter} | Retain messages contain latest value and modification timestamp for {parameter} received by device. All new received messages by device also generate dedicated publication per each {parameter} into specified topic. |
| flespi/state/gw/devices/{id}/settings/{name} | Retain messages contain current device {name} setting value, objects state for more information |
| flespi/state/gw/plugins/{plugin_id}/devices/{device_id} | Retain messages contain plugin configuration of specified device. |
| flespi/rest/{method}/{api-uri} | Use any existing {method} to manipulate flespi instances in {api-uri}}, see REST API over MQTT for more information |
| flespi/interval/gw/calcs/{calc_id}/devices/{device_id}/{event} | Interval generated by calculator {calc_id} for device {device_id} was updated by the system. Possible {event} types are: created, deleted, updated. See flespi analytics for more information. |
MQTT session
MQTT connection can be opened with a clean-session flag. In a clean-session mode subscriptions and undelivered messages are removed as soon as the connection to the broker closes. Non-clean session is persistent — it keeps undelivered messages and subscriptions until the new connection to the broker is established. The idling period for flespi MQTT broker is 10 days.
MQTT broker
You can access flespi MQTT broker via special REST API to manage sessions, subscribe and unsubscribe them to different topics and even to publish MQTT messages with HTTP call.
flespi objects state
The topic flespi/state/{api}/{origin}/{id}/{property} contains {api} objects property values. This function is responsible for the properties that are valuable to define current state of flespi objects: name, configuration, storage buffer size, counters, etc. Usage:
- receive current values as retained messages on subscription;
- receive new property values as soon as object state changes;
- learn more in the corresponding blog article.
REST API over MQTT
Publish to topic flespi/rest/{method}/{api-uri} to perform REST API call to flespi platform. {method} should be valid for specified {api-uri}. Optional data parameter may be passed as MQTT message payload. MQTT v5.0 accepts "response topic" parameter with the indication of topic to which to publish response to API call. Otherwise response is published to the same topic.
Additional user property "response_cid" allows to redirect response to another subaccount. This is a special feature when you want to query some API call on top-level and redirect result from flespi broker directly to one of the subaccounts.
And one more feature is "response_chunked" user property. If it is contain "true" value, then response will be chunkied in multiple MQTT messages. Message with specified "http_code" user property is the indication of the last chunk(message).
Learn more in the corresponding blog article.
MQTT API FAQ
- fast: receive data as soon as it appears inside flespi platform
- safe: connection is secured with SSL certificates
- scalable: subscribe only for the desired topics
- easy: no need to send REST API calls each time you want to receive data
- reliable: don’t forget that we guarantee 99.9% system uptime (for each and every component of the flespi platform), which allows you to build reliable applications based on our solutions.
You can use one of several MQTT clients available for free, e.g. MQTT.fx is a multiplatform GUI tool to work with MQTT brokers.
Yes, flespi MQTT broker can be used as a connection hub between different IoT devices operating via MQTT. Telemetry MQTT devices can publish messages to flespi MQTT broker to any topic (except API topics beginning with “flespi” prefix - as a 1st topic level). Using flespi MQTT broker relieves you from developing and supporting your own MQTT broker. And your IoT hub application can just subscribe to the required topics to receive the telemetry data.
To use flespi MQTT broker just authorize at flespi panel with any of your OpenID accounts, create one or multiple tokens and that's all. Your MQTT namespace is private and nobody can access it except by using tokens connected to your flespi account. You can use it for free until you are OK with limits or do need commercial SLA.
Yes our MQTT broker has full websockets support. You can use wss://mqtt.flespi.io/ for secured connection to port 443 (recommended) or use plain websocket connection over standard HTTP 80 port with ws://mqtt.flespi.io/.
Yes you can create a group of MQTT clients connected to shared topic like $share/group_name/topic/name. where $share prefix tells MQTT broker to distribute messages for /topic/name topic between randomly selected members of the group_name group. You can read more in the dedicated article.