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 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 a built-in flespi panel MQTT Board. 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 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 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 one must connect to 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 flespi token used as MQTT connection username. Leave the password blank. Tokens may have ACL. The number of possible MQTT sessions is limited.
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 topic flespi/message/gw/devices/456/test.
Each time a channel receives a message the MQTT client will get it in the subscription.
MQTT connection advantages:
Store undelivered messages
If your MQTT client occasionally loses connection to the MQTT broker, it can receive messages undelivered during the offline period. This can be achieved with a persistent session. Subscription must be done with QoS = 1. In this case, the MQTT broker remembers the client_ID of MQTT connection, stores messages if the client is offline, and sends them as soon as the client connects again.
You can create several MQTT clients connected to one topic to process messages from flespi in parallel. This can be achieved with shared subscriptions. Insert prefix $share/group_name/ before desired subscription topic 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 must 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. Channel messages will not be stored in the channel’s buffer. Undelivered messages will be stored in MQTT session storage and removed after delivery to your platform.