MQTT is the most usable, flexible, fast, and reliable way to get messages from flespi. To receive new channel messages via MQTT you need to accomplish the following steps:
1. Create an MQTT client
MQTT client is an instance that can receive messages over MQTT protocol.
For debugging purposes, it may be a UI tool like MQTTbox or MQTT Board built into the flespi panel.
For integration use, it may be any language. The flespi team contributed to the open-source MQTT.js library. Python users may use gmqtt (flespi example) created by Gurtam developers. Or any other MQTT implementation compatible with MQTT protocol versions 3.1, 3.1.1, 5.0.
2. Establish MQTT connection to flespi MQTT broker
MQTT client must know the broker address to establish an MQTT connection. flespi MQTT broker is hosted at mqtt.flespi.io. Connection port varies depending on the connection type:
- 8883 for TCP over SSL
- 1883 for TCP non-SSL
- 443 for WebSockets over SSL
- 80 for WebSockets non-SSL
So, e.g. to connect to flespi MQTT broker via WebSockets over SSL you should use the following URI: mqtt.flespi.io:443.
3. Authorize with flespi Token as username
MQTT client must authorize to get access to internal flespi resources. Authorization is done via the flespi token used as an MQTT connection username.
Leave the password blank.
You can configure ACL for the token to restrict access to a specific topic(s)/subtopic(s) only.
The number of possible MQTT sessions is limited by the account type.
4. Subscribe for messages
The flespi MQTT API page includes a table with topics to receive info from flespi. E.g. to receive messages from devices connected to the channel with id=123 MQTT client must subscribe to the topic flespi/message/gw/channels/123/+. To receive messages from the device with id=456 named ‘test’ MQTT client may subscribe to the topic flespi/message/gw/devices/456.
Each time a channel receives a message the MQTT client will get it in the subscription.
Why use MQTT?
Store undelivered messages
If your MQTT client occasionally loses connection to the MQTT broker, it can receive messages undelivered during the offline period. This is done using persistent sessions. Subscription must be done with QoS=1. In this case, the MQTT broker remembers the client_ID of the MQTT connection, stores messages while the client is offline, and sends them as soon as the client gets back online.Load balancing
You can create several MQTT clients connected to one topic to process messages from flespi in parallel. This can be achieved with shared subscriptions. Prepend the target subscription topic with the $share/group_name/ prefix and flespi MQTT broker will randomly distribute messages between all subscribers.- Don’t store data in flespi channels
If you use the flespi channel intensively, you should take care of deleting messages from the channel’s internal message storage. If it is overflowed (see limits), the channel will be blocked. You can avoid this by using MQTT sessions and setting messages_ttl for the channel to 0. Then channel messages will not be stored in the channel buffer. Undelivered messages will be stored in MQTT session storage and removed upon delivery to your platform.