MQTT API
Event-based alternative to the REST API with SSL-protected connections, high-precision data extraction, and no need for repeated requests.
The MQTT protocol ensures fast and secure message delivery so you receive an event message in MQTT session once 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
| Configuration | |
|---|---|
| Host |
mqtt.flespi.io for EU region ru-mqtt.flespi.io for RU region |
| Port |
MQTT over TCP: 8883 (SSL) or 1883 (non-SSL) MQTT over WebSockets: 443 (SSL) or 80 (non-SSL) |
| MQTT version | 3.1, 3.1.1, 5.0 |
| QoS supported | QoS 0, QoS 1, QoS 2 |
| Topic | you can publish messages to any topic except flespi/ |
| Authorization | ||
|---|---|---|
| Username | Password | ClientID |
| your flespi token | not used * | any |
|
* Alternatively, if it's more convenient and secure for your client library, you can put a flespi token into the Password field instead of Username.
** For MQTT clients with a 16-byte limit on username or password fields, you may use special authorization. |
||
You may play with MQTT API using MQTT Board — client tool for MQTT debugging and testing. You can open an already preconfigured and connected instance of MQTT Board directly in flespi.io — this is the best way to do an initial investigation of the flespi MQTT API.
MQTT topics
Below is the list of built-in topics with flespi platform events:
| Topic | Desription |
|---|---|
| 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 (up to 10 days).
MQTT broker
You can access flespi MQTT broker via special REST API to manage sessions, subscribe and unsubscribe to different topics, and even publish MQTT messages with HTTP calls.
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 the flespi platform. {method} should be valid for the specified {api-uri}. Optional data parameter may be passed as MQTT message payload. MQTT v5.0 accepts "response topic" parameter with the indication of the topic to which to publish a response to API call. Otherwise, the response is published to the same topic.
Additional user property "response_cid" allows redirecting the response to another subaccount. This is a special feature helpful when you want to perform an API call on the top-level (from the master account) and redirect its result from the flespi broker directly to one of the subaccounts.
One more feature is the "response_chunked" user property. If it's "true", the response will be chunked in multiple MQTT messages. A message with the specified "http_code" user property is the indication of the last chunk (message).
Learn more in the corresponding blog article.