MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimize network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery power are at a premium. (source MQTT.org)

Tago has it own MQTT broker that is responsible to push the data to the clients in case something new is published in the specific topics subscribed by them. As a simple example, we can build a system where a sensor sends temperature data to a topic whenever it gets an update. From the other side, we may have devices that would like to be notified when this data arrive, so they subscribe to this topic. When the data is ready, the temperature sensor publishes the data in that topic, and the broker is responsible to push it to all devices that subscribed to the same topic.

With this basic idea, it is possible to combine the MQTT with Tago’s amazing capabilities to not only enable the communication among devices, but also to create dashboards, analytics, notifications, and reports.

MQTT methods

MQTT defines methods (or verbs) to indicate the desired action to be performed on the identified resource.

Connect: Waits for a connection to be established with the server.

Disconnect: Waits for the MQTT client to finish any work it must do, and for the TCP/IP session to disconnect.

Subscribe: Waits for completion of the Subscribe or UnSubscribe method.

UnSubscribe: Requests the server unsubscribe the client from one or more topics.

Publish: Returns immediately to the application thread after passing the request to the MQTT client.

Security

Encryption across the network can be handled with SSL, independently of the MQTT protocol itself (it is worth noting that SSL is not the lightest of protocols, and does add significant network overhead). Additional security can be added by an application encrypting data that it sends and receives, but this is not something built-in to the protocol, in order to keep it simple and lightweight. At Tago, you can send your data encrypted direct to your Analysis and decrypt it then insert the data on your Bucket, you can use this way to increase your security if your data are sensitive or you want to add an extra layer of security.

Connection

Hostmqtt.tago.ioTCP/IP port1883TCP/IP port over SSL8883usernameany valuepassword<Account token or Device token>

Topics

A topic is used to send messages to the connected clients, and it consists of one or more topic levels, the levels are separated by a forward slash ‘/’.

Wildcards

Wildcards are used by the clients to subscribe to multiple topics at once, the client can only use wildcards to subscribe to topics, it means the client cannot publish to a topic using wildcards.

Tago MQTT broker supports single level and multi level wildcards

Single level

The single level is represented by the + sign, by adding a + sign to the topic.

Example

If the client subscribes to the topic home/+/temperature, the following topics will match:

  • home/kitchen/temperature
  • home/office/temperature
  • home/livingroom/temperature

That means if any client publishes data to these topics above, the subscribed client will receive it.

The following topics WILL NOT match:

  • home/kitchen
  • home/kitchen/humidity
  • home/office/ac/temperature

Multi level

The multi level is represented by the # sign, by adding a # sign to the topic the client will subscribe to all the following levels of that topic.

Example

If the client subscribes to the topic home/#, the following topics will match:

  • home/kitchen
  • home/kitchen/temperature
  • home/office/ac/temperature
  • home/upstairs/bedroom/ac/temperature

Debug topic

Tago MQTT broker has a debug topic which is tago/debug if a client subscribes to this topic, it will receive debug messages.

The messages are triggered with the following actions.

  • a client subscribes to any topic
  • a client unsubscribes to any topic
  • a client publishes to any topic

Retained Messages

Retained messages are normal MQTT messages, but sent with the retained flag set to true. Tago MQTT broker will save the last retained message and QoS for that topic and each client that subscribes to that topic will receive this message immediately after subscribing to the topic. If the client sends another retained message to the same topic, the old retained message will be overwritten.

If the subscribing client uses a wildcard and match the topic, it will receive the message.

Send a retained message

To send a retained message, the client must set the payload and the retained flag to true, each MQTT client library provides an easy way to do that.

Delete a retained message

To delete a retained message, the client must set the retained flag to true and no payload. By sending a retained message without a payload Tago MQTT broker will delete it.

PUBLISHING TO TAGO

The Tago MQTT Broker reserves a topic named tago, you can use that topic only to send data or trigger an Analysis, but not for any other specific function. Below is a list of the functions that you can use. You can use any topic to create a communication among the devices, but if you want to reach the devices/data buckets/analysis/actions in your account at Tago, you need to use these reserved topics.

TopicMQTT MethodContent TypeToken Typetago/data/postpublishJSON as StringDevicetago/analysis/Analysis_IDpublishAnythingDevice / Account

tago/data/post

Use this topic to send data from any device to the data bucket in your account. The figue below shows the flow from the device to its bucket. At Tago, the device-token used should be linked to the desired data bucket. When the data arrives in your bucket, it is stored, and it will be ready for visualization or to take any other action.

You should send the data using the same JSON format as you would send it by API, you can see all your options here.

tago/analysis/Your_Analysis_ID_HERE

Use this topic to send a payload data from a device in any format to be first parsed by your own script. The script should be uploaded on the analysis that is identified by the analysis_id. This option gives you a lot of flexibility to interpret any kind of data or protocol according to your own application. The figure below, shows the data flow from the device to the specific analysis associated with the ID used in the topic.

You can send any data format with any content to this topic, your data will go directly to your Analysis inside the scope on the first position of the array. The data will not be stored automatically, your script needs to take care of it.

PUBLISHING FROM TAGO

You can publish to your MQTT topics by coding a script that will run from an Analysis. When the analysis runs, your script can publish a topic that can be received by any device that subscribed to that specific topic. There are different ways to start an analysis, it may be by timer, an Action, or called by another analysis. The figure below shows the data flow from the analysis to the MQTT network.


Remember, don’t publish to any of the reserved topics if you want to reach external devices.