Automatically translate this page?

How To Consume Telematics Hub Messages Via MQTT

Connecting to flespi MQTT broker and getting channel and device data via MQTT API.

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 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, 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.

  • 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. 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, 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.

See also
Helping you quickly go through the real-life issues.
Figuring out at what step in the connectivity chain the problem is and how to fix it.